Macos App Store Readiness

macOS App Store Readiness Audit

A systematic audit framework for checking whether a macOS app project meets Apple's App Store submission requirements. Covers project configuration, sandbox, hardened runtime, code signing, notarization, privacy, review guidelines, network, UI/UX, and submission metadata.

Output: An HTML report saved to {project_directory}/app-store-readiness-report.html with severity-scored findings and specific remediation steps.

Severity Levels

Category Status Rules:

• FAIL: Any Critical or High finding exists
• WARN: Only Medium findings exist
• PASS: Only Low findings or no findings

Analysis Workflow

When the user asks to audit a macOS app, follow these steps in order.

Step 1: Project Discovery

Locate the project structure by running these commands:

# Find Xcode project
find "$PROJECT_DIR" -maxdepth 3 -name "*.xcodeproj" -o -name "*.xcworkspace" 2>/dev/null

# Find Info.plist files
find "$PROJECT_DIR" -name "Info.plist" -not -path "*/Pods/*" -not -path "*/Build/*" 2>/dev/null

# Find entitlements files
find "$PROJECT_DIR" -name "*.entitlements" 2>/dev/null

# Find privacy manifest
find "$PROJECT_DIR" -name "PrivacyInfo.xcprivacy" 2>/dev/null

# Find source code directories
find "$PROJECT_DIR" -type d -name "*.swift" -o -name "*.m" -o -name "*.h" 2>/dev/null | head -5
# Also check for top-level source dirs
ls "$PROJECT_DIR"/*.swift "$PROJECT_DIR"/Sources/ "$PROJECT_DIR"/App/ 2>/dev/null

Determine project type by grepping source code:

• SwiftUI: import SwiftUI or @main with App protocol
• AppKit: import AppKit or NSApplication
• Catalyst: import UIKit with macOS target
• Electron: package.json with electron dependency
• Flutter/React Native: corresponding config files

Determine distribution type by grepping project.pbxproj:

• CODE_SIGN_IDENTITY = "Apple Distribution" or "3rd Party Mac Developer Application" → Mac App Store
• CODE_SIGN_IDENTITY = "Developer ID Application" → Direct distribution (notarization required)
• CODE_SIGN_IDENTITY = "Apple Development" → Development only (not ready)

Step 2: File Analysis

For each discovered file, read and extract relevant information:

project.pbxproj — grep for these build settings:

grep -E "(MACOSX_DEPLOYMENT_TARGET|ENABLE_HARDENED_RUNTIME|CODE_SIGN_IDENTITY|CODE_SIGN_ENTITLEMENTS|CODE_SIGN_STYLE|DEVELOPMENT_TEAM|PROVISIONING_PROFILE|PRODUCT_BUNDLE_IDENTIFIER|OTHER_CODE_SIGN_FLAGS|ARCHS|EXCLUDED_ARCHS|INFOPLIST_FILE|GENERATE_INFOPLIST_FILE)" project.pbxproj | sort -u

Info.plist — read and check for required keys. If GENERATE_INFOPLIST_FILE = YES in build settings, some keys may be in the build settings instead.

Entitlements files — read each .entitlements file and list all declared entitlements.

PrivacyInfo.xcprivacy — read and validate the structure (XML plist format).

Source code — scan for API usage patterns:

# Privacy APIs
grep -r "ATTrackingManager\|CNContactStore\|CLLocationManager\|AVCaptureDevice\|AVAudioSession\|PHPhotoLibrary\|EKEventStore\|CBCentralManager" --include="*.swift" --include="*.m" "$SRC_DIR"

# Networking
grep -r "NSURLConnection\|UIWebView\|WKWebView\|URLSession\|NSAppTransportSecurity" --include="*.swift" --include="*.m" "$SRC_DIR"

# Accessibility
grep -r "accessibilityLabel\|accessibilityIdentifier\|setAccessibilityLabel\|AccessibilityElement\|VoiceOver" --include="*.swift" --include="*.m" "$SRC_DIR"

# Deprecated APIs
grep -r "UIWebView\|UIAlertView\|UIActionSheet\|addressBookRef\|ABAddressBook" --include="*.swift" --include="*.m" "$SRC_DIR"

# IPv4 literals
grep -rE "\b[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\b" --include="*.swift" --include="*.m" --include="*.plist" "$SRC_DIR" | grep -v "127.0.0.1\|0.0.0.0\|255.255.255"

# Placeholder content
grep -ri "TODO\|FIXME\|lorem ipsum\|placeholder\|sample text" --include="*.swift" --include="*.m" --include="*.storyboard" --include="*.xib" "$SRC_DIR"

# StoreKit
grep -r "SKPaymentQueue\|StoreKit\|Product\|Transaction" --include="*.swift" "$SRC_DIR" | head -10

# ATT (App Tracking Transparency)
grep -r "ATTrackingManager\|requestTrackingAuthorization\|NSUserTrackingUsageDescription" --include="*.swift" --include="*.m" "$SRC_DIR"

# Third-party SDK privacy manifests
find "$PROJECT_DIR" -path "*/Pods/*" -name "PrivacyInfo.xcprivacy" -o -path "*/*.framework/*" -name "PrivacyInfo.xcprivacy" -o -path "*/*.xcframework/*" -name "PrivacyInfo.xcprivacy" 2>/dev/null

# Account deletion
grep -r "deleteAccount\|deleteUser\|removeAccount\|accountDeletion" --include="*.swift" "$SRC_DIR"

Step 3: Checklist Evaluation

Go through each of the 10 categories below. For every checklist item, determine:

• PASS: Requirement is met
• WARN: Requirement is partially met or has concerns
• FAIL: Requirement is not met
• N/A: Requirement does not apply to this app (explain why)

Step 4: Scoring

Calculate scores:

• Category score: PASS if all items pass or are N/A; WARN if only medium findings; FAIL if any Critical/High findings
• Overall readiness: (passing categories / applicable categories) × 100%
• Readiness gauge: Red (< 60%), Yellow (60-85%), Green (> 85%)

Step 5: Generate HTML Report

Generate a self-contained HTML file (inline CSS, no external dependencies) and save it to {project_directory}/app-store-readiness-report.html. Use the report template specified at the end of this document.

After generating the report, print a summary to the user in the conversation:

1. Overall readiness percentage and category breakdown
2. Top 3 most critical items to fix first
3. If all categories pass, note the app appears ready for submission

Category 1: Project Configuration

Verifies that the Xcode project and Info.plist are correctly configured for Mac App Store distribution.

Notes:

• If GENERATE_INFOPLIST_FILE = YES, some keys may be auto-generated from build settings. Check both locations.
• If INFOPLIST_FILE points to a file that doesn't exist, this is a Critical finding.

Category 2: App Sandbox

App Sandbox is mandatory for Mac App Store distribution. This category checks whether it is enabled and whether entitlements follow the principle of least privilege.

Notes:

• For sandboxed apps, file access outside the container requires NSOpenPanel/NSSavePanel (Powerbox) or security-scoped bookmarks (com.apple.security.files.bookmarks.app-scope).
• If the app needs to access files across app launches, it must use security-scoped bookmarks with the bookmarks.app-scope entitlement.

Category 3: Hardened Runtime

Hardened Runtime protects the app from code injection, dylib hijacking, and memory tampering. It is required for notarization and Mac App Store submission.

Notes:

• Electron apps may need allow-unsigned-executable-memory and disable-library-validation depending on version. Newer Electron versions (28+) require fewer exceptions.
• Apps embedding Python, Lua, or other interpreters may need allow-jit.
• Each exception entitlement must be justified in the App Review notes.

Category 4: Code Signing

All macOS apps must be properly code-signed. This category verifies the signing configuration.

Notes:

• If a built .app bundle exists, run codesign -dvv YourApp.app to inspect actual signing state.
• --deep is considered harmful because it signs in an undefined order and may miss some items.

Category 5: Notarization

Notarization is an automated Apple security check. It is required for Developer ID distribution (outside Mac App Store). For Mac App Store distribution, the App Store handles this — but configuration must still be correct.

Notes:

• For Mac App Store distribution: notarization is handled by Apple during the upload process. These checks are informational.
• For Developer ID distribution: notarization is mandatory since macOS 10.15 Catalina. Apps will show a Gatekeeper warning if not notarized.

Category 6: Privacy

Apple's privacy requirements are one of the most common rejection reasons. This category checks privacy manifests, usage descriptions, and tracking transparency.

Required Reason APIs (must be declared in PrivacyInfo.xcprivacy if used):

ATT Implementation Pattern (macOS):

import AppTrackingTransparency

func requestTrackingPermission() async {
    let status = await ATTrackingManager.requestTrackingAuthorization()
    switch status {
    case .authorized:
        // Enable tracking, initialize ad SDKs with tracking
        break
    case .denied, .restricted:
        // Use non-personalized ads, disable cross-app tracking
        break
    case .notDetermined:
        // Should not happen after request, handle gracefully
        break
    @unknown default:
        break
    }
}

Timing: Request ATT permission after the app has launched and the user has context. Do not show the prompt immediately on first launch.

Usage Description String Quality — Apple rejects vague descriptions:

// REJECTED — too vague
"This app needs access to your camera."

// APPROVED — specific purpose
"The camera is used to scan barcodes for price comparison."

// REJECTED — too vague
"This app needs your location."

// APPROVED — specific purpose
"Your location is used to show nearby restaurants on the map."

Category 7: App Store Review Guidelines

Maps the most commonly cited rejection reasons to concrete checks.

Category 8: Network and Connectivity

Apps must work correctly on modern networks, including IPv6-only environments.

Category 9: UI/UX and Accessibility

Apps must follow Apple's Human Interface Guidelines and support accessibility features.

Category 10: Submission Readiness

Metadata and App Store Connect readiness checklist.

Submission Workflow

When the app passes all audit categories, follow this workflow for submission:

1. Archive in Xcode. Product → Archive (requires a Distribution signing identity). Verify zero warnings in Release configuration.
2. Upload to App Store Connect. Use the Organizer window (Distribute App → App Store Connect) or xcodebuild -exportArchive. Transporter also works.
3. TestFlight internal testing. Available to your team within minutes of processing. Walk through every screen on at least two Mac configurations.
4. TestFlight external testing. External groups require Beta App Review (usually < 24 hours). Validate with real users before full submission.
5. Submit for App Review. In App Store Connect, select the build, fill all metadata, attach screenshots, click Submit. Average review time is under 24 hours; allow 48 hours.

Phased Release

After approval, you can enable phased release for gradual rollout:

Users who manually check for updates receive the update immediately regardless of phased release stage. You can pause, resume, or complete the rollout at any time from App Store Connect.

Expedited Review Requests

Apple grants expedited reviews for critical situations only:

• Critical bug fix affecting existing users
• Time-sensitive event (holiday launch, legal compliance deadline)
• Security vulnerability patch

Request via the Contact Us form in App Store Connect (App Review → Expedite Request). Provide a specific, factual justification.

Appeal Process

If your app is rejected, all rejections appear in the Resolution Center in App Store Connect:

1. Read the rejection carefully — it cites the specific guideline violated.
2. Reply in the Resolution Center with a clear, factual explanation.
3. If you fixed the issue, describe exactly what changed and resubmit the binary.
4. If you believe the rejection is incorrect, explain why your app complies with references to the specific guideline text.

Tone matters. Be professional, specific, and concise. Provide demo credentials, screenshots, or screen recordings that demonstrate compliance.

Escalation to App Review Board

If the Resolution Center exchange does not resolve the issue:

1. Request an appeal to the App Review Board via the Resolution Center or the App Store Contact form (App Review → Appeal).
2. The Board is a separate team from the original reviewer. Provide all context.
3. Board decisions are final for that submission, but you can modify and resubmit.

Successful Appeal Strategies

• Provide a video walkthrough showing the feature the reviewer could not find.
• Cite the specific guideline and explain how the app satisfies each requirement.
• Include demo credentials if the reviewer could not log in.
• Reference precedent — if similar macOS apps exist on the App Store with the same pattern, note them respectfully.
• Offer a compromise — if Apple objects to a specific implementation, propose an alternative.

Common Mistakes Quick Reference

These are the most frequent reasons macOS apps get rejected. Use this as a final sanity check before submission:

1. Missing demo credentials — Provide App Review login credentials in App Store Connect notes. Most Guideline 2.1 rejections are from reviewers unable to test behind a login.
2. Privacy manifest mismatch — Declared data collection in PrivacyInfo.xcprivacy must match App Store privacy nutrition labels and actual network traffic. Apple cross-references all three.
3. Unnecessary ATT prompt — Do not show the App Tracking Transparency prompt unless you actually track users across apps/websites. Apple rejects unnecessary prompts.
4. Vague usage descriptions — "This app needs your location" is rejected. State the specific feature that uses the data.
5. External payment links for digital content — Any language or button directing users to purchase digital content outside the app is rejected.
6. Missing App Sandbox — Mac App Store apps without sandbox enabled will be automatically rejected.
7. Hardened Runtime not enabled — Required for notarization and Mac App Store submission.
8. Temporary exception entitlements — These are heavily scrutinized and often rejected. Find alternatives.
9. Placeholder content visible — Remove all TODO, lorem ipsum, test data, and placeholder images before submission.
10. Screenshots don't match actual UI — Screenshots must show the real app, not mockups or marketing renders.

HTML Report Template

Generate a self-contained HTML file using this structure. The CSS should be inline — no external dependencies.

Structure:
├── Header
│   ├── Title: "macOS App Store Readiness Report"
│   ├── App name, Bundle ID, scan date
│   └── Readiness gauge (percentage with color coding)
├── Executive Summary
│   ├── PASS / WARN / FAIL counts
│   └── Overall readiness score with gauge
├── Category Summary Table
│   └── One row per category: name, status badge, finding count, summary
├── Detailed Findings (collapsible per category)
│   └── Each finding: severity badge, check name, description, remediation
├── Remediation Priority (action plan)
│   └── Ordered list of all Critical/High findings with specific fix instructions
└── Footer
    ├── Generation timestamp
    └── Disclaimer about manual review requirements

CSS Styling Guidelines:

• Dark header (#1a1a2e background, white text)
• Severity badges: Critical = #dc3545, High = #fd7e14, Medium = #ffc107, Low = #6c757d
• Status badges: PASS = #28a745, WARN = #ffc107, FAIL = #dc3545
• Readiness gauge: Red (< 60%), Yellow (60-85%), Green (> 85%)
• Use <details> / <summary> for collapsible category sections
• Alternating row colors for tables
• Responsive layout for readability on different screen sizes

References

• App Store Review Guidelines
• App Sandbox
• Hardened Runtime
• Notarizing macOS Software
• Privacy Manifest Files
• Required Reason API Codes
• Entitlements
• macOS Human Interface Guidelines
• Information Property List
• Code Signing
• App Store Connect Help
• App Tracking Transparency
• StoreKit 2