Skill: Private API Audit

Purpose

Detects usage of private Apple APIs, undocumented frameworks, and runtime introspection patterns that bypass the public SDK — enforcing Guideline 2.5.1 which allows only public APIs and frameworks. Private API usage causes automated binary rejection at upload and account termination on repeated violations.

Apple Guideline

• Primary: 2.5.1 — Performance: Public APIs Only
• Related: 2.5.4
• Reference: references/guidelines/2-performance.md

Real-World Rejection Cases

• Case: App used dlopen to load a private framework at runtime — rejected with ITMS-90338 "Non-public API usage" during automated binary analysis
  Source: Apple Developer Forums (multiple reports)
  Root cause: Apple's automated binary analysis scans for dlopen calls and symbol references to non-public frameworks — even if the app passes human review, the binary scanner will catch private API usage and reject with a specific ITMS error code

• Case: App called [UIDevice _supportsForceTouch] via performSelector to detect 3D Touch capability on older devices — Apple's binary scanner flagged the underscore-prefixed private method
  Source: Stack Overflow (private API detection reports)
  Root cause: Apple's static analysis flags any symbol beginning with an underscore that resolves to a private UIKit or Foundation method — use only public APIs with @available checks for feature detection

• Case: App used NSClassFromString(@"_UIBackdropView") to access a private UIKit view class for a visual effect — binary was rejected before human review
  Source: Apple Developer Forums (2.5.1 enforcement reports)
  Root cause: NSClassFromString with internal Apple class names (prefixed with _UI, _NS, CA) is treated as private API usage by the binary scanner

Trigger

Invoke on any iOS/macOS project before App Store submission to detect private API patterns that cause automated rejection.

Inputs

Name	Type	Default	Description
project_root	path	cwd	iOS/macOS project root
shared_context	object	nil	Pre-collected context from appstore-full-audit Phase 1

Actions

Phase 1: Context Collection

Skip this phase if shared_context is provided.

1. Glob **/*.swift — collect all Swift source files.
2. Glob **/*.m **/*.mm — collect Objective-C source files.
3. Glob **/*.h — collect header files for private symbol imports.

Phase 2: Checks

1. dlopen usage
   Grep pattern dlopen|dlsym|NSBundle.*load|Bundle.*load in **/*.swift and **/*.m.
   Any match → 🔴 CRITICAL. dlopen and dynamic library loading of private frameworks triggers ITMS-90338 automated rejection.

2. NSClassFromString with private class names
   Grep pattern NSClassFromString in **/*.swift and **/*.m.
   For each match, Read surrounding context — if the string argument starts with _UI, _NS, _CA, UI_ → 🔴 CRITICAL. Private UIKit/Foundation class access via NSClassFromString is detected by Apple's binary scanner.

3. Underscore-prefixed Apple method calls
   Grep pattern \._[a-z][a-zA-Z]*\(|performSelector.*@"_ in **/*.swift and **/*.m.
   Any match on UIKit/Foundation objects → 🟠 HIGH. Underscore-prefixed methods are private — Apple's binary scanner flags them regardless of whether they are called via performSelector or direct invocation.

4. Method swizzling on system classes
   Grep pattern method_exchangeImplementations|swizzle|class_replaceMethod|method_setImplementation in **/*.swift and **/*.m.
   Any match targeting system framework classes (UIViewController, UIApplication, NSObject subclasses) → 🟠 HIGH. Swizzling Apple system classes is fragile, may break across iOS versions, and may be flagged as private API abuse.

5. Private framework imports
   Grep pattern #import <SpringBoard|#import <BackBoardServices|#import <FrontBoard|SpringBoardServices|GraphicsServices in **/*.h and **/*.m.
   Any match → 🔴 CRITICAL. Private framework headers are not permitted in App Store submissions.

Phase 3: Output

Collect all findings from Phase 2 and build the prioritised findings list below. Include file paths and line numbers. Omit tiers with no findings.

Output Format

## Private API Audit — Findings

### 🔴 CRITICAL — Guaranteed rejection
- [ ] TODO: Remove dlopen() call — loading private frameworks triggers ITMS-90338 automated binary rejection — `NativeLoader.m:15` — Guideline 2.5.1
- [ ] TODO: Remove NSClassFromString("_UIBackdropView") — private UIKit class access detected by Apple binary scanner — `VisualEffectHelper.swift:22` — Guideline 2.5.1
- [ ] TODO: Remove SpringBoardServices import — private framework not permitted in App Store submissions — `SpringBoardBridge.h:1` — Guideline 2.5.1

### 🟠 HIGH — Very likely rejection
- [ ] TODO: Replace _supportsForceTouch with public traitCollection.forceTouchCapability check — `TouchHandler.m:45` — Guideline 2.5.1
- [ ] TODO: Remove UIViewController swizzling — replace with subclassing or composition pattern — `Analytics.swift:88` — Guideline 2.5.1

### 🟡 MEDIUM — Possible rejection
- [ ] TODO: Review all method_exchangeImplementations calls — swizzling system classes may break on future iOS versions and may be flagged in binary analysis

### 🟢 LOW — Best practice
- [ ] TODO: Run `nm -u MyApp.app/MyApp | grep ' _' | grep -v 'OBJC_CLASS'` on the release binary to check for private symbol references before submission

Tools Used

Glob, Grep, Read

Constraints

• Read-only. No file edits.
• No network calls.
• Skip Phase 1 if shared_context is provided by orchestrating agent.
• Third-party SDKs can introduce private API usage — check dependency frameworks too. Run otool -L on the final binary to list all linked libraries.

Quick Commands

# Check for dlopen / dynamic loading
!grep -rn "dlopen\|dlsym\|NSBundle.*load\|Bundle.*load" . --include="*.swift" --include="*.m" | grep -v "//"

# Check for private class access via NSClassFromString
!grep -rn "NSClassFromString" . --include="*.swift" --include="*.m" -A1 | grep -E "_UI|_NS|_CA"

# Check for underscore-prefixed method calls
!grep -rn "\._[a-z]" . --include="*.swift" --include="*.m" | grep -v "//\|_:\|_endIndex\|_read\|_modify"

# Check for method swizzling
!grep -rn "method_exchangeImplementations\|swizzle\|class_replaceMethod" . --include="*.swift" --include="*.m"

Swift Anti-Pattern Reference

examples/swift/PrivateAPIPatterns.swift

Detection Steps

1. Find target files

   • Glob: **/*.swift, **/*.m

2. Search for rejection patterns

   • Grep dlopen\|dlsym — dynamic linking to private frameworks
   • Grep NSClassFromString — dynamic class lookup (check argument for private class names like _UIBackgroundTaskInfo, SpringBoard, _UIApplication)
   • Grep method_exchangeImplementations\|class_replaceMethod\|class_addMethod — method swizzling
   • Grep _[a-z][a-zA-Z]*: in .m files only — ObjC underscore-prefixed private selectors
   • Grep performSelector\|perform(_:with:\|perform(_:) — check selector name for leading underscore

3. Determine verdict

   • Any dlopen/dlsym usage → 🔴 CRITICAL (Guideline 2.5.1, ITMS-90338)
   • NSClassFromString with private class name → 🔴 CRITICAL
   • Method swizzling of system classes → 🔴 CRITICAL
   • No private API patterns found → 🟢 pass

4. Report

   • File path + line number of each private API usage
   • Fix: Remove all dynamic linking and private selector calls; use only public APIs documented at developer.apple.com