feat(browser-extension): publish Safari apps to App Store Connect

Author: chrisbbreuer

storage/framework/core/browser-extension/README.md

@@ -29,9 +29,14 @@ Safari with MAIN-world content scripts + `match_about_blank`).
 ```sh
 buddy extension:safari:init   # scaffold the Xcode container app into safari/
 buddy extension:safari:app    # build + sync into the appex + xcodebuild
+buddy extension:safari:publish # signed archive + App Store Connect upload
 ```
 
 Set `safariBundleId` in the config (the appex gets `<safariBundleId>.Extension`)
+and `safariTeamId` to the Apple Developer team used for signing. Publishing
+reads `APP_STORE_CONNECT_API_KEY_ID`, `APP_STORE_CONNECT_API_ISSUER_ID`, and
+`APP_STORE_CONNECT_API_KEY_PATH` from the environment. Run with
+`--validate-only` to exercise Apple's validation without uploading a build.
 and list any build output that is not part of the extension (marketing pages,
 etc.) in `safariExclude` so it stays out of the appex. The scaffold mirrors
 what `xcrun safari-web-extension-converter` generates, so day-to-day work

storage/framework/core/browser-extension/safari-template/README.md

@@ -36,7 +36,8 @@ Safari > Settings > Extensions, granting it website access.
 
 ## Signing
 
-The project ships with `DEVELOPMENT_TEAM` empty so anyone can build.
+The project uses `safariTeamId` when configured and otherwise leaves
+`DEVELOPMENT_TEAM` empty so anyone can build.
 
 Local, unsigned (no Apple account): the default build uses
 `CODE_SIGNING_ALLOWED=NO`. Unsigned extensions require

storage/framework/core/browser-extension/safari-template/__APP_NAME__.xcodeproj/project.pbxproj

@@ -371,7 +371,7 @@
 				CODE_SIGN_ENTITLEMENTS = __APP_NAME__/__APP_NAME__.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
-				DEVELOPMENT_TEAM = "";
+				DEVELOPMENT_TEAM = "__DEVELOPMENT_TEAM__";
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST = NO;
 				INFOPLIST_FILE = __APP_NAME__/Info.plist;
@@ -394,7 +394,7 @@
 				CODE_SIGN_ENTITLEMENTS = __APP_NAME__/__APP_NAME__.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
-				DEVELOPMENT_TEAM = "";
+				DEVELOPMENT_TEAM = "__DEVELOPMENT_TEAM__";
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST = NO;
 				INFOPLIST_FILE = __APP_NAME__/Info.plist;
@@ -415,7 +415,7 @@
 			buildSettings = {
 				CODE_SIGN_ENTITLEMENTS = "__APP_NAME__ Extension/__APP_NAME___Extension.entitlements";
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = "";
+				DEVELOPMENT_TEAM = "__DEVELOPMENT_TEAM__";
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST = NO;
 				INFOPLIST_FILE = "__APP_NAME__ Extension/Info.plist";
@@ -437,7 +437,7 @@
 			buildSettings = {
 				CODE_SIGN_ENTITLEMENTS = "__APP_NAME__ Extension/__APP_NAME___Extension.entitlements";
 				CODE_SIGN_STYLE = Automatic;
-				DEVELOPMENT_TEAM = "";
+				DEVELOPMENT_TEAM = "__DEVELOPMENT_TEAM__";
 				ENABLE_HARDENED_RUNTIME = YES;
 				GENERATE_INFOPLIST = NO;
 				INFOPLIST_FILE = "__APP_NAME__ Extension/Info.plist";

storage/framework/core/browser-extension/src/safari.ts

@@ -45,6 +45,7 @@ interface ScaffoldVars {
   bundleId: string
   extBundleId: string
   version: string
+  teamId: string
 }
 
 function fillTemplate(text: string, vars: ScaffoldVars): string {
@@ -54,6 +55,7 @@ function fillTemplate(text: string, vars: ScaffoldVars): string {
     .replaceAll('__APP_DISPLAY_NAME__', vars.displayName)
     .replaceAll('__APP_NAME__', vars.appName)
     .replaceAll('__MARKETING_VERSION__', vars.version)
+    .replaceAll('__DEVELOPMENT_TEAM__', vars.teamId)
     .replaceAll('__YEAR__', String(new Date().getFullYear()))
 }
 
@@ -76,6 +78,8 @@ export interface SafariScaffoldOptions {
   version?: string
   /** Directory of source PNG icons for the AppIcon set. @default the built chrome outdir's icons, else `public/icons` */
   iconsDir?: string
+  /** Apple Developer team used for automatic signing. @default config.safariTeamId */
+  teamId?: string
   cwd?: string
 }
 
@@ -96,6 +100,7 @@ export async function scaffoldSafariApp(config: ExtensionConfig, options: Safari
     bundleId,
     extBundleId: `${bundleId}.Extension`,
     version: options.version ?? '0.1.0',
+    teamId: options.teamId ?? config.safariTeamId ?? '',
   }
 
   if (!options.bundleId && !config.safariBundleId)
@@ -275,3 +280,112 @@ export async function buildSafariApp(config: ExtensionConfig, options: SafariApp
 
   return { appPath: join(derivedData, 'Build', 'Products', configuration, `${appName}.app`), resources }
 }
+
+export interface AppStoreConnectAuth {
+  /** App Store Connect API key ID. @default APP_STORE_CONNECT_API_KEY_ID */
+  keyId?: string
+  /** App Store Connect API issuer ID. @default APP_STORE_CONNECT_API_ISSUER_ID */
+  issuerId?: string
+  /** Filesystem path to the AuthKey_*.p8 file. @default APP_STORE_CONNECT_API_KEY_PATH */
+  keyPath?: string
+}
+
+export interface SafariPublishOptions extends SafariSyncOptions, AppStoreConnectAuth {
+  /** Extension marketing version. */
+  version: string
+  /** Monotonically increasing CFBundleVersion. @default GITHUB_RUN_NUMBER or current Unix time */
+  buildNumber?: string
+  /** Apple Developer team. @default config.safariTeamId */
+  teamId?: string
+  /** Build and validate without uploading to App Store Connect. @default false */
+  validateOnly?: boolean
+  /** Rebuild the Safari web-extension payload before archiving. @default true */
+  build?: boolean
+}
+
+function appStoreConnectAuth(options: AppStoreConnectAuth): Required<AppStoreConnectAuth> {
+  const keyId = options.keyId ?? process.env.APP_STORE_CONNECT_API_KEY_ID
+  const issuerId = options.issuerId ?? process.env.APP_STORE_CONNECT_API_ISSUER_ID
+  const keyPath = options.keyPath ?? process.env.APP_STORE_CONNECT_API_KEY_PATH
+  const missing = [
+    !keyId && 'APP_STORE_CONNECT_API_KEY_ID',
+    !issuerId && 'APP_STORE_CONNECT_API_ISSUER_ID',
+    !keyPath && 'APP_STORE_CONNECT_API_KEY_PATH',
+  ].filter(Boolean)
+  if (missing.length)
+    throw new Error(`[browser-extension] missing App Store Connect credentials: ${missing.join(', ')}`)
+  if (!existsSync(resolve(keyPath!)))
+    throw new Error(`[browser-extension] App Store Connect API key not found: ${resolve(keyPath!)}`)
+  return { keyId: keyId!, issuerId: issuerId!, keyPath: resolve(keyPath!) }
+}
+
+function xcodeAuthArgs(auth: Required<AppStoreConnectAuth>): string[] {
+  return [
+    '-allowProvisioningUpdates',
+    '-authenticationKeyPath', auth.keyPath,
+    '-authenticationKeyID', auth.keyId,
+    '-authenticationKeyIssuerID', auth.issuerId,
+  ]
+}
+
+function exportOptionsPlist(method: 'app-store-connect' | 'validation', teamId: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>destination</key>
+  <string>upload</string>
+  <key>manageAppVersionAndBuildNumber</key>
+  <false/>
+  <key>method</key>
+  <string>${method}</string>
+  <key>signingStyle</key>
+  <string>automatic</string>
+  <key>teamID</key>
+  <string>${teamId}</string>
+  <key>uploadSymbols</key>
+  <true/>
+</dict>
+</plist>
+`
+}
+
+/**
+ * Create a signed Release archive and either validate it or upload it to App
+ * Store Connect. Xcode owns certificate/profile creation and the upload so the
+ * same command works locally and in macOS CI with an API key.
+ */
+export async function publishSafariApp(config: ExtensionConfig, options: SafariPublishOptions): Promise<{ archivePath: string, exportPath: string, buildNumber: string }> {
+  const cwd = options.cwd ?? process.cwd()
+  const teamId = options.teamId ?? config.safariTeamId
+  if (!teamId)
+    throw new Error('[browser-extension] Safari publishing needs safariTeamId in config/extension.ts or --team-id')
+  const auth = appStoreConnectAuth(options)
+  const buildNumber = options.buildNumber ?? process.env.GITHUB_RUN_NUMBER ?? String(Math.floor(Date.now() / 1000))
+  if (!/^\d+(?:\.\d+){0,2}$/.test(buildNumber))
+    throw new Error(`[browser-extension] invalid Safari build number ${buildNumber}; use one to three dot-separated integers`)
+
+  if (options.build !== false)
+    await buildExtension(config, { target: 'safari', version: options.version, cwd })
+  await syncSafariResources(config, options)
+
+  const appName = safariAppName(config)
+  const dir = safariProjectDir(cwd, options.dir)
+  const buildDir = join(dir, 'build')
+  const archivePath = join(buildDir, `${appName}.xcarchive`)
+  const exportPath = join(buildDir, options.validateOnly ? 'validation' : 'upload')
+  const plistPath = join(buildDir, options.validateOnly ? 'ExportOptions.validation.plist' : 'ExportOptions.app-store.plist')
+  const authArgs = xcodeAuthArgs(auth)
+  await mkdir(buildDir, { recursive: true })
+  await rm(archivePath, { recursive: true, force: true })
+  await rm(exportPath, { recursive: true, force: true })
+
+  const project = join(dir, `${appName}.xcodeproj`)
+  await Bun.$`xcodebuild -project ${project} -scheme ${appName} -configuration Release -destination generic/platform=macOS -archivePath ${archivePath} MARKETING_VERSION=${options.version} CURRENT_PROJECT_VERSION=${buildNumber} DEVELOPMENT_TEAM=${teamId} ${authArgs} archive`
+
+  const method = options.validateOnly ? 'validation' : 'app-store-connect'
+  await Bun.write(plistPath, exportOptionsPlist(method, teamId))
+  await Bun.$`xcodebuild -exportArchive -archivePath ${archivePath} -exportPath ${exportPath} -exportOptionsPlist ${plistPath} ${authArgs}`
+
+  return { archivePath, exportPath, buildNumber }
+}

storage/framework/core/browser-extension/src/types.ts

@@ -97,6 +97,8 @@ export interface ExtensionConfig {
    * (`extension:safari:init`); the appex uses `<safariBundleId>.Extension`.
    */
   safariBundleId?: string
+  /** Apple Developer team used to sign and publish the Safari container app. */
+  safariTeamId?: string
   /**
    * Build-output files to keep out of the Safari appex Resources when syncing
    * (e.g. marketing-site pages that are built into dist but are not part of

storage/framework/core/browser-extension/tests/safari.test.ts

@@ -13,6 +13,7 @@ const config: ExtensionConfig = {
   description: 'Fixture config for the safari target.',
   geckoId: 'extension@example.com',
   safariBundleId: 'com.example.TestExtension',
+  safariTeamId: 'TEAM123456',
   safariExclude: ['marketing.html', 'marketing.js'],
   background: 'src/background/index.ts',
   content: [
@@ -114,6 +115,7 @@ describe('safari scaffold + sync', () => {
     expect(pbxproj).toContain('PRODUCT_BUNDLE_IDENTIFIER = com.example.TestExtension;')
     expect(pbxproj).toContain('PRODUCT_BUNDLE_IDENTIFIER = com.example.TestExtension.Extension;')
     expect(pbxproj).toContain('MARKETING_VERSION = 1.2.3;')
+    expect(pbxproj).toContain('DEVELOPMENT_TEAM = "TEAM123456";')
     expect(pbxproj).not.toContain('__APP_NAME__')
 
     const appPlist = await Bun.file(join(dir, 'TestExtension', 'Info.plist')).text()

storage/framework/core/buddy/src/commands/extension.ts

@@ -93,13 +93,15 @@ export function extension(buddy: CLI): void {
     .option('--bundle-id <id>', 'Base bundle identifier (defaults to config safariBundleId)')
     .option('--dir <dir>', 'Output directory for the Xcode project (default safari)')
     .option('--force', 'Overwrite existing scaffold files')
-    .action(async (options: { bundleId?: string, dir?: string, force?: boolean }) => {
+    .option('--team-id <id>', 'Apple Developer team used for signing')
+    .action(async (options: { bundleId?: string, dir?: string, force?: boolean, teamId?: string }) => {
       const { scaffoldSafariApp } = await import('@stacksjs/browser-extension')
       const { config } = await load()
       const { dir, written, skipped } = await scaffoldSafariApp(config, {
         bundleId: options.bundleId,
         dir: options.dir,
         force: Boolean(options.force),
+        teamId: options.teamId,
       })
       log.success(`Scaffolded the Safari container app → ${dir} (${written.length} files)`)
       if (skipped.length)
@@ -129,4 +131,30 @@ export function extension(buddy: CLI): void {
         log.success(`Extension payload synced → ${resources}`)
       }
     })
+
+  buddy
+    .command('extension:safari:publish', 'Archive and validate or upload the Safari app to App Store Connect')
+    .option('--version <version>', 'Override the marketing version (defaults to package.json)')
+    .option('--build-number <number>', 'CFBundleVersion (defaults to GITHUB_RUN_NUMBER or Unix time)')
+    .option('--team-id <id>', 'Apple Developer team (defaults to config safariTeamId)')
+    .option('--api-key-id <id>', 'App Store Connect API key ID')
+    .option('--api-issuer-id <id>', 'App Store Connect API issuer ID')
+    .option('--api-key-path <path>', 'Path to the App Store Connect AuthKey_*.p8 file')
+    .option('--validate-only', 'Create and validate the archive without uploading it')
+    .action(async (options: { version?: string, buildNumber?: string, teamId?: string, apiKeyId?: string, apiIssuerId?: string, apiKeyPath?: string, validateOnly?: boolean }) => {
+      const { publishSafariApp } = await import('@stacksjs/browser-extension')
+      const { config, version } = await load()
+      const result = await publishSafariApp(config, {
+        version: options.version ?? version,
+        buildNumber: options.buildNumber,
+        teamId: options.teamId,
+        keyId: options.apiKeyId,
+        issuerId: options.apiIssuerId,
+        keyPath: options.apiKeyPath,
+        validateOnly: Boolean(options.validateOnly),
+      })
+      log.success(options.validateOnly
+        ? `Validated Safari archive ${result.archivePath} (build ${result.buildNumber})`
+        : `Uploaded Safari build ${result.buildNumber} to App Store Connect`)
+    })
 }

storage/framework/core/buddy/src/lazy-commands.ts

@@ -44,6 +44,7 @@ const commandRegistry: Record<string, CommandLoader> = {
   'extension:package': { path: './commands/extension.ts', exportName: 'extension' },
   'extension:safari:init': { path: './commands/extension.ts', exportName: 'extension' },
   'extension:safari:app': { path: './commands/extension.ts', exportName: 'extension' },
+  'extension:safari:publish': { path: './commands/extension.ts', exportName: 'extension' },
   // Feature install / uninstall — single file registers all pairs.
   'dashboard:install': { path: './commands/features.ts', exportName: 'features' },
   'dashboard:uninstall': { path: './commands/features.ts', exportName: 'features' },