@mondaydotcomorg/z2h-cli 0.1.1 → 0.3.0

package/dist/esm/commands/dev.mjs

@@ -1,4 +1,6 @@
-import { readJson } from 'fs-extra';
+import path from 'node:path';
+import fs from 'node:fs';
+import { writeFile, readJson } from 'fs-extra';
 import { watch } from 'chokidar';
 import { execa } from 'execa';
 import { setOutputMode, info, output, warn, errorLog } from '../util/logger.mjs';
@@ -22,6 +24,28 @@ async function devCommand(opts) {
         cwd: ctx.paths.shadowDir,
         stdio: ['inherit', 'pipe', 'inherit'],
     });
+    const pidFile = path.join(ctx.paths.shadowDir, 'dev.pid');
+    if (server.pid) {
+        await writeFile(pidFile, String(server.pid));
+    }
+    const cleanupPid = () => {
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch (_) {
+            // file already gone — ignore
+        }
+    };
+    server.on('exit', cleanupPid);
+    process.on('exit', cleanupPid);
+    process.on('SIGINT', () => {
+        server.kill();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        server.kill();
+        process.exit(0);
+    });
     let readyPrinted = false;
     server.stdout?.on('data', (chunk) => {
         process.stdout.write(chunk);

package/dist/esm/commands/generate-z2h-token.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_TOKEN_PAGE_URL = "https://bigbrain.me/bigbrain-vibe/generate-z2h-token";
+export declare const LOOPBACK_TIMEOUT_MS = 120000;
+export interface GenerateZ2HTokenOptions {
+    /**
+     * Skip browser auto-open AND skip the loopback callback. Prints the URL
+     * for the user to open manually, then waits for them to paste the token
+     * into the prompt. Use for SSH sessions, CI, or when the loopback can't
+     * reach the CLI for any reason.
+     */
+    noBrowser?: boolean;
+    /** Override the page URL — useful when pointing at staging. */
+    url?: string;
+    json?: boolean;
+}
+export declare function generateZ2HTokenCommand(opts?: GenerateZ2HTokenOptions): Promise<void>;
+//# sourceMappingURL=generate-z2h-token.d.ts.map

package/dist/esm/commands/generate-z2h-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-z2h-token.d.ts","sourceRoot":"","sources":["../../../src/commands/generate-z2h-token.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB,yDAAyD,CAAC;AAC7F,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAE3C,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAuED,wBAAsB,uBAAuB,CAAC,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B/F"}

package/dist/esm/commands/generate-z2h-token.mjs

@@ -0,0 +1,99 @@
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { execa } from 'execa';
+import { setOutputMode, warn, output, info } from '../util/logger.mjs';
+import { validateJwtPattern, writeZthAuth } from '../util/auth/write-auth.mjs';
+import { startLoopbackServer } from '../util/auth/loopback-server.mjs';
+
+const DEFAULT_TOKEN_PAGE_URL = 'https://bigbrain.me/bigbrain-vibe/generate-z2h-token';
+const LOOPBACK_TIMEOUT_MS = 120_000;
+function browserOpenCommand() {
+    switch (process.platform) {
+        case 'darwin':
+            return 'open';
+        case 'win32':
+            return 'start';
+        default:
+            return 'xdg-open';
+    }
+}
+async function openInBrowser(url) {
+    await execa(browserOpenCommand(), [url], { stdio: 'ignore' });
+}
+async function promptForToken() {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        const raw = await rl.question('Paste your token here, then press Enter:\n> ');
+        return raw.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+function withQueryParam(url, key, value) {
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}${key}=${encodeURIComponent(value)}`;
+}
+async function runManualFlow(pageUrl) {
+    info(`open this URL in your browser to mint a Z2H deploy token:\n` +
+        `  ${pageUrl}\n\n` +
+        `1. Click "Generate token" on the page.\n` +
+        `2. Copy the token shown.\n` +
+        `3. Paste it below and press Enter.\n`);
+    const token = await promptForToken();
+    if (!token) {
+        throw new Error('No token entered.');
+    }
+    return token;
+}
+async function runLoopbackFlow(pageUrl) {
+    const loopback = await startLoopbackServer();
+    const fullUrl = withQueryParam(pageUrl, 'cli_callback', loopback.callbackUrl);
+    info('opening your browser to mint a Z2H deploy token');
+    info(`  ${fullUrl}`);
+    try {
+        await openInBrowser(fullUrl);
+    }
+    catch {
+        warn('could not auto-open the browser. please visit the URL above manually.');
+    }
+    info('waiting for the page to send the token (Ctrl+C to fall back to manual paste)…');
+    try {
+        return await loopback.waitForToken(LOOPBACK_TIMEOUT_MS);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        loopback.close();
+    }
+}
+async function generateZ2HTokenCommand(opts = {}) {
+    if (opts.json) {
+        setOutputMode('json');
+    }
+    const pageUrl = opts.url ?? process.env.Z2H_TOKEN_PAGE_URL ?? DEFAULT_TOKEN_PAGE_URL;
+    // --no-browser bypasses both auto-open and the loopback round-trip — the
+    // user opens the URL themselves and pastes the token. Useful when the
+    // loopback can't be reached (SSH, CI, locked-down browsers).
+    let token = null;
+    if (!opts.noBrowser) {
+        token = await runLoopbackFlow(pageUrl);
+        if (!token) {
+            warn('loopback flow timed out or was cancelled — falling back to manual paste.');
+        }
+    }
+    if (!token) {
+        token = await runManualFlow(pageUrl);
+    }
+    if (!validateJwtPattern(token)) {
+        throw new Error('That does not look like a JWT (expected three dot-separated segments).');
+    }
+    const { filePath } = await writeZthAuth({ token });
+    output(`[z2h-cli] token saved ✅ ${filePath}`, {
+        ok: true,
+        filePath,
+    });
+}
+
+export { DEFAULT_TOKEN_PAGE_URL, LOOPBACK_TIMEOUT_MS, generateZ2HTokenCommand };

package/dist/esm/constants.d.ts

@@ -9,4 +9,12 @@ export declare const MIN_PORT = 13000;
 export declare const MAX_PORT = 19999;
 export declare const GITIGNORE_ENTRIES: string[];
 export declare const YARNRC_LINES: string[];
+export declare const BUCKET_WRITE_NAME = "prod-use1-bigbrain-zth-mf-assets";
+export declare const REGION = "us-east-1";
+export declare const BUCKET_WRITE_URL = "https://prod-use1-bigbrain-zth-mf-assets.s3.us-east-1.amazonaws.com";
+export declare const BUCKET_READ_DNS_NAME = "bigbrain-zth-mf-assets";
+export declare const BUCKET_READ_DNS_URL = "https://bigbrain-zth-mf-assets.bigbrain.me";
+export declare const MANIFEST_KEY = "mf-assets";
+export declare const MANIFEST_READ_URL = "https://bigbrain-zth-mf-assets.bigbrain.me/mf-assets";
+export declare const APP_NAME_PATTERN: RegExp;
 //# sourceMappingURL=constants.d.ts.map

package/dist/esm/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGjD,CAAC;AAQF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAG3C,eAAO,MAAM,YAAY,UAIxB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,eAAe,SAAS,CAAC;AAGtC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGjD,CAAC;AAQF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAElD,CAAC;AAMF,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAC9B,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAG9B,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAG3C,eAAO,MAAM,YAAY,UAIxB,CAAC;AAQF,eAAO,MAAM,iBAAiB,qCAAqC,CAAC;AACpE,eAAO,MAAM,MAAM,cAAc,CAAC;AAClC,eAAO,MAAM,gBAAgB,wEAA4D,CAAC;AAE1F,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,+CAAgD,CAAC;AAKjF,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,iBAAiB,yDAA2C,CAAC;AAM1E,eAAO,MAAM,gBAAgB,QAA2B,CAAC"}

package/dist/esm/constants.mjs

@@ -32,5 +32,25 @@ const YARNRC_LINES = [
     "npmAuthToken: '${NPM_TOKEN}'",
     "npmRegistryServer: 'https://registry.npmjs.org/'",
 ];
+// ─────────── Z2H deploy bucket / contract ─────────
+// Source of truth for the bucket layout. The CLI uses these when configuring
+// the S3 client + uploading; bigbrain-zth's STS broker imports them via
+// `@mondaydotcomorg/z2h-cli/constants` to scope the per-deploy session
+// policy to the same bucket + manifest key.
+const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
+const REGION = 'us-east-1';
+const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
+const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
+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.
+const MANIFEST_KEY = 'mf-assets';
+const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
+// ─────────── App-name slug — backend & CLI both honor this ─────
+// Lowercase kebab-case, must start with a letter, 2-50 chars total. The
+// backend STS broker rejects anything else with 400; the CLI can validate
+// upfront for friendlier errors.
+const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
 
-export { GITIGNORE_ENTRIES, MAX_PORT, MIN_PORT, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, YARNRC_LINES };
+export { APP_NAME_PATTERN, BUCKET_READ_DNS_NAME, BUCKET_READ_DNS_URL, BUCKET_WRITE_NAME, BUCKET_WRITE_URL, GITIGNORE_ENTRIES, MANIFEST_KEY, MANIFEST_READ_URL, MAX_PORT, MIN_PORT, REGION, SHADOW_DEV_DEPS, SHADOW_DIR_NAME, SHADOW_SCRIPTS, YARNRC_LINES };

package/dist/esm/index.mjs

@@ -5,6 +5,7 @@ import { cleanCommand } from './commands/clean.mjs';
 import { deployCommand } from './commands/deploy.mjs';
 import { createWorkspaceCommand } from './commands/create-workspace.mjs';
 import { createCommand } from './commands/create.mjs';
+import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { errorLog, fail } from './util/logger.mjs';
 
 async function main() {
@@ -88,6 +89,20 @@ async function main() {
             fail(`create-workspace failed: ${err.message}`, { command: 'create-workspace' }, 1);
         }
     });
+    program
+        .command('generate-z2h-token')
+        .description('Open the bigbrain.me token page, capture the token via a loopback callback, and persist it to ~/.zth/auth.json')
+        .option('--no-browser', "don't auto-open the browser; print the URL and prompt for manual paste")
+        .option('--url <url>', 'Override the token page URL (e.g. for staging)')
+        .option('--json', 'emit structured JSON on stdout')
+        .action(async (opts) => {
+        try {
+            await generateZ2HTokenCommand(opts);
+        }
+        catch (err) {
+            fail(`generate-z2h-token failed: ${err.message}`, { command: 'generate-z2h-token' }, 1);
+        }
+    });
     program
         .command('create <app-name>')
         .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')

package/dist/esm/shadow/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/shadow/scaffold.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAqG9C;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvG"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/shadow/scaffold.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA0G9C;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvG"}

package/dist/esm/shadow/scaffold.mjs

@@ -73,6 +73,11 @@ declare module '*.wasm' {
   const e: string;
   export default e;
 }
+
+declare module '*.html?url' {
+  const src: string;
+  export default src;
+}
 `;
 const TSCONFIG_TEMPLATE = {
     compilerOptions: {

package/dist/esm/templates/app/claude-settings.mjs

@@ -3,8 +3,21 @@ var permissions = {
 		"Skill(z2h:*)"
 	]
 };
+var hooks = {
+	Stop: [
+		{
+			hooks: [
+				{
+					type: "command",
+					command: "if [ -f .zth/dev.pid ]; then kill $(cat .zth/dev.pid) 2>/dev/null; rm .zth/dev.pid; fi"
+				}
+			]
+		}
+	]
+};
 const claudeSettings = {
-	permissions: permissions
+	permissions: permissions,
+	hooks: hooks
 };
 
-export { claudeSettings as default, permissions };
+export { claudeSettings as default, hooks, permissions };

package/dist/esm/util/auth/__tests__/auth-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-store.test.d.ts.map

package/dist/esm/util/auth/__tests__/auth-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-store.test.d.ts","sourceRoot":"","sources":["../../../../../src/util/auth/__tests__/auth-store.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/auth/__tests__/broker-credential-provider.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=broker-credential-provider.test.d.ts.map

package/dist/esm/util/auth/__tests__/broker-credential-provider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-credential-provider.test.d.ts","sourceRoot":"","sources":["../../../../../src/util/auth/__tests__/broker-credential-provider.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/auth/__tests__/loopback-server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loopback-server.test.d.ts.map

package/dist/esm/util/auth/__tests__/loopback-server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-server.test.d.ts","sourceRoot":"","sources":["../../../../../src/util/auth/__tests__/loopback-server.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/auth/__tests__/write-auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=write-auth.test.d.ts.map

package/dist/esm/util/auth/__tests__/write-auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-auth.test.d.ts","sourceRoot":"","sources":["../../../../../src/util/auth/__tests__/write-auth.test.ts"],"names":[],"mappings":""}

package/dist/esm/util/auth/auth-store.d.ts

@@ -0,0 +1,11 @@
+export declare const Z2H_AUTH_DIR: string;
+export declare const Z2H_AUTH_FILE: string;
+export interface ZthAuth {
+    token: string;
+}
+export declare class Z2hAuthMissingError extends Error {
+    readonly authFilePath: string;
+    constructor(authFilePath: string);
+}
+export declare function readZthAuth(): Promise<ZthAuth>;
+//# sourceMappingURL=auth-store.d.ts.map

package/dist/esm/util/auth/auth-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/auth-store.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,YAAY,QAAkC,CAAC;AAC5D,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAIjD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CASpD"}

package/dist/esm/util/auth/auth-store.mjs

@@ -0,0 +1,29 @@
+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.
+const Z2H_AUTH_DIR = path.join(os.homedir(), '.zth');
+const Z2H_AUTH_FILE = path.join(Z2H_AUTH_DIR, 'auth.json');
+class Z2hAuthMissingError extends Error {
+    authFilePath;
+    constructor(authFilePath) {
+        super(`No Z2H deploy token found at ${authFilePath}. Please run 'z2h-cli generate-z2h-token' command.`);
+        this.authFilePath = authFilePath;
+        this.name = 'Z2hAuthMissingError';
+    }
+}
+async function readZthAuth() {
+    if (!(await pathExists(Z2H_AUTH_FILE))) {
+        throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
+    }
+    const parsed = (await readJson(Z2H_AUTH_FILE));
+    if (!parsed.token) {
+        throw new Error(`${Z2H_AUTH_FILE} is missing a "token" string field.`);
+    }
+    return { token: parsed.token };
+}
+
+export { Z2H_AUTH_DIR, Z2H_AUTH_FILE, Z2hAuthMissingError, readZthAuth };

package/dist/esm/util/auth/broker-credential-provider.d.ts

@@ -0,0 +1,12 @@
+import type { AwsCredentialIdentityProvider } from '@aws-sdk/types';
+export declare const DEFAULT_BROKER_BASE_URL = "https://bigbrain-zth.bigbrain.me";
+export declare const STS_BROKER_PATH = "/z2h-cli/sts/credentials";
+/**
+ * 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 declare function brokerCredentialProvider({ appName }: {
+    appName: string;
+}): AwsCredentialIdentityProvider;
+//# sourceMappingURL=broker-credential-provider.d.ts.map

package/dist/esm/util/auth/broker-credential-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-credential-provider.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/broker-credential-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAyB,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAE3F,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAC1E,eAAO,MAAM,eAAe,6BAA6B,CAAC;AA4D1D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,6BAA6B,CAuBxG"}

package/dist/esm/util/auth/broker-credential-provider.mjs

@@ -0,0 +1,76 @@
+import { readZthAuth } from './auth-store.mjs';
+
+const DEFAULT_BROKER_BASE_URL = 'https://bigbrain-zth.bigbrain.me';
+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;
+function brokerBaseUrl() {
+    return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
+}
+async function fetchCredentialsOnce(appName) {
+    const { token } = await readZthAuth();
+    const url = `${brokerBaseUrl()}${STS_BROKER_PATH}`;
+    let res;
+    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());
+    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.
+ */
+function brokerCredentialProvider({ appName }) {
+    let cached;
+    let inflight;
+    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;
+    };
+}
+
+export { DEFAULT_BROKER_BASE_URL, STS_BROKER_PATH, brokerCredentialProvider };

package/dist/esm/util/auth/loopback-server.d.ts

@@ -0,0 +1,12 @@
+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 declare function startLoopbackServer(): Promise<LoopbackHandle>;
+//# sourceMappingURL=loopback-server.d.ts.map

package/dist/esm/util/auth/loopback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-server.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/loopback-server.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,cAAc,CAAC,CAkF7D"}

package/dist/esm/util/auth/loopback-server.mjs

@@ -0,0 +1,87 @@
+import cors from 'cors';
+import express, { json } from 'express';
+
+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;
+function startLoopbackServer() {
+    return new Promise((resolve, reject) => {
+        let resolveToken = null;
+        let rejectToken = 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;
+            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();
+            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((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);
+    });
+}
+
+export { startLoopbackServer };

package/dist/esm/util/auth/write-auth.d.ts

@@ -0,0 +1,11 @@
+import { type ZthAuth } from './auth-store';
+export declare function writeZthAuth(auth: ZthAuth): Promise<{
+    filePath: string;
+}>;
+/**
+ * Three base64url segments separated by dots — a structural sanity check,
+ * not a real verification. Server-side validation happens at the STS broker.
+ */
+export declare function validateJwtPattern(token: string): boolean;
+export { Z2H_AUTH_FILE } from './auth-store';
+//# sourceMappingURL=write-auth.d.ts.map

package/dist/esm/util/auth/write-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-auth.d.ts","sourceRoot":"","sources":["../../../../src/util/auth/write-auth.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAMzE,wBAAsB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAK/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/util/auth/write-auth.mjs

@@ -0,0 +1,22 @@
+import { chmod } from 'node:fs/promises';
+import { ensureDir, writeFile } from 'fs-extra';
+import { Z2H_AUTH_DIR, Z2H_AUTH_FILE } from './auth-store.mjs';
+
+// 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;
+async function writeZthAuth(auth) {
+    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.
+ */
+function validateJwtPattern(token) {
+    return /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
+}
+
+export { Z2H_AUTH_FILE, validateJwtPattern, writeZthAuth };

package/dist/esm/util/manifest.d.ts

@@ -22,6 +22,7 @@ export interface AssetManifestFile {
 export interface ManifestEntry extends AssetManifestFile {
     version: number;
     url: string;
+    deployedBy: string;
 }
 export type Manifest = Record<string, ManifestEntry>;
 export declare function readManifest(): Promise<Manifest>;

package/dist/esm/util/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/util/manifest.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAQtD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,UAI1D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,CAE3F;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/util/manifest.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAQtD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,UAI1D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,CAE3F;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE"}

package/dist/esm/util/manifest.mjs

@@ -1,5 +1,6 @@
 import { PutObjectCommand } from '@aws-sdk/client-s3';
-import { MANIFEST_READ_URL, getS3Client, BUCKET_WRITE_NAME, MANIFEST_KEY } from './s3/client.mjs';
+import { MANIFEST_READ_URL, BUCKET_WRITE_NAME, MANIFEST_KEY } from '../constants.mjs';
+import { getS3Client } from './s3/client.mjs';
 
 async function readManifest() {
     // Read via the public CDN endpoint, no AWS auth required.

package/dist/esm/util/s3/client.d.ts

@@ -1,11 +1,10 @@
 import { S3Client } from '@aws-sdk/client-s3';
-export declare const BUCKET_WRITE_NAME = "prod-use1-bigbrain-zth-mf-assets";
-export declare const REGION = "us-east-1";
-export declare const BUCKET_WRITE_URL = "https://prod-use1-bigbrain-zth-mf-assets.s3.us-east-1.amazonaws.com";
-export declare const BUCKET_READ_DNS_NAME = "bigbrain-zth-mf-assets";
-export declare const BUCKET_READ_DNS_URL = "https://bigbrain-zth-mf-assets.bigbrain.me";
-export declare const MANIFEST_KEY = "mf-assets";
-export declare const MANIFEST_READ_URL = "https://bigbrain-zth-mf-assets.bigbrain.me/mf-assets";
+/**
+ * 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 declare function setupS3Client({ appName }: {
+    appName: string;
+}): void;
 export declare function getS3Client(): S3Client;
-export declare function assertBucketExists(): Promise<void>;
 //# sourceMappingURL=client.d.ts.map