@mondaydotcomorg/z2h-cli 0.2.0 → 0.3.1

package/src/commands/deploy.ts

@@ -1,8 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { pathExists, readJson } from 'fs-extra';
-import { execa } from 'execa';
-import { info, warn, output, setOutputMode } from '../util/logger';
+import { info, output, setOutputMode } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
 import {
   nextVersion,
@@ -13,36 +12,22 @@ import {
   type ManifestEntry,
 } from '../util/manifest';
 import { uploadDir } from '../util/s3/upload';
-import { assertBucketExists, BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL } from '../util/s3/client';
+import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL } from '../constants';
+import { setupS3Client } from '../util/s3/client';
+import { readZthAuth } from '../util/auth/auth-store';
 import { cleanAppName, mfAppName } from '../util/app-name';
 import { buildCommand } from './build';
 
-const APONO_BUNDLE = '<APONO_BUNDLE_NAME>'; // TODO: replace with actual bundle name once infra setup is complete
-
 export interface DeployOptions {
   dryRun?: boolean;
   json?: boolean;
 }
 
-async function requestAponoAccess(): Promise<void> {
-  if (APONO_BUNDLE === '<APONO_BUNDLE_NAME>') {
-    warn(
-      `skipping Apono request — APONO_BUNDLE is still a placeholder ("${APONO_BUNDLE}"). Set it in deploy.ts before relying on auto-grant.`
-    );
-    return;
-  }
-  info(`requesting Apono access for bundle "${APONO_BUNDLE}"`);
-  await execa('apono', ['bundles', 'grant', APONO_BUNDLE], { stdio: 'inherit' });
-}
-
 export async function deployCommand(opts: DeployOptions): Promise<void> {
   if (opts.json) {
     setOutputMode('json');
   }
 
-  info('checking S3 bucket');
-  await assertBucketExists();
-
   const paths = resolveConsumerPaths(process.cwd());
   const consumerPkg = (await readJson(paths.consumerPkg)) as { name?: string };
   if (!consumerPkg.name) {
@@ -50,6 +35,11 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
   }
   const appName = mfAppName(consumerPkg.name);
 
+  // Validate the user's deploy token is on disk before doing any expensive
+  // work. Throws Z2hAuthMissingError with a remediation hint if not.
+  await readZthAuth();
+  setupS3Client({ appName });
+
   info('reading current Z2H manifest');
   const manifest = await readManifest();
   const version = nextVersion(manifest, appName);
@@ -70,6 +60,14 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
   }
   const assetManifest = (await readJson(assetManifestPath)) as AssetManifestFile;
 
+  const deployedBy = os.userInfo().username;
+  const entry: ManifestEntry = {
+    ...assetManifest,
+    version,
+    url,
+    deployedBy,
+  };
+
   if (opts.dryRun) {
     output(`[z2h-cli] dry-run: would upload to s3://${BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
       ok: true,
@@ -79,22 +77,11 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
       bucket: BUCKET_WRITE_NAME,
       keyPrefix,
       url,
-      entry: { ...assetManifest, version, url },
+      entry,
     });
     return;
   }
 
-  await requestAponoAccess();
-
-  const deployedBy = os.userInfo().username;
-
-  const entry: ManifestEntry = {
-    ...assetManifest,
-    version,
-    url,
-    deployedBy,
-  };
-
   info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
   await uploadDir(paths.shadowBuild, keyPrefix);
 

package/src/commands/generate-z2h-token.ts

@@ -0,0 +1,124 @@
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { execa } from 'execa';
+import { info, warn, output, setOutputMode } from '../util/logger';
+import { writeZthAuth, validateJwtPattern } from '../util/auth/write-auth';
+import { startLoopbackServer } from '../util/auth/loopback-server';
+
+export const DEFAULT_TOKEN_PAGE_URL = 'https://bigbrain.me/bigbrain-vibe/generate-z2h-token';
+export const LOOPBACK_TIMEOUT_MS = 120_000;
+
+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;
+}
+
+function browserOpenCommand(): string {
+  switch (process.platform) {
+    case 'darwin':
+      return 'open';
+    case 'win32':
+      return 'start';
+    default:
+      return 'xdg-open';
+  }
+}
+
+async function openInBrowser(url: string): Promise<void> {
+  await execa(browserOpenCommand(), [url], { stdio: 'ignore' });
+}
+
+async function promptForToken(): Promise<string> {
+  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: string, key: string, value: string): string {
+  const sep = url.includes('?') ? '&' : '?';
+  return `${url}${sep}${key}=${encodeURIComponent(value)}`;
+}
+
+async function runManualFlow(pageUrl: string): Promise<string> {
+  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: string): Promise<string | null> {
+  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();
+  }
+}
+
+export async function generateZ2HTokenCommand(opts: GenerateZ2HTokenOptions = {}): Promise<void> {
+  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: string | null = 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,
+  });
+}

package/src/constants.ts

@@ -38,3 +38,28 @@ export 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.
+
+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}`;
+
+// ─────────── 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.
+export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;

package/src/index.ts

@@ -1,3 +1,4 @@
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
@@ -5,8 +6,11 @@ import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand } from './commands/create';
+import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { errorLog, fail } from './util/logger';
 
+const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
+
 async function main(): Promise<void> {
   const program = new Command();
   program
@@ -25,7 +29,7 @@ async function main(): Promise<void> {
         '  2  system error (yarn install or trident build failed)',
       ].join('\n')
     )
-    .version('0.0.0');
+    .version(version);
 
   program
     .command('build')
@@ -91,6 +95,22 @@ async function main(): Promise<void> {
       }
     });
 
+  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: { noBrowser?: boolean; url?: string; json?: boolean }) => {
+      try {
+        await generateZ2HTokenCommand(opts);
+      } catch (err) {
+        fail(`generate-z2h-token failed: ${(err as Error).message}`, { command: 'generate-z2h-token' }, 1);
+      }
+    });
+
   program
     .command('create <app-name>')
     .description('Scaffold a new Z2H consumer app inside ~/zth-projects/')

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 };
+}