feat: enforce adult privacy across catalog entities

Author: LamPPKK

README.md

@@ -33,7 +33,7 @@ The two native mobile apps keep platform-specific UI and storage while sharing t
 - **Read catalog reviews and follow recommendations** with full review bodies, blank/duplicate removal, localized author fallbacks, optional rating/date metadata, same-media-type TMDb recommendations, current-title exclusion, a separate similar-titles shelf, and adult-title filtering unless the local PIN is unlocked on Apple, Apple TV, and every full Android/KMP catalog client.
 - **Understand every regional edition** through production-company/network links, region-matched certification and release date, alternative titles, localized translations, and external identifiers decoded by typed native models.
 - **See where to watch** by device or chosen region for stream/rent/buy offers, with TMDb links and required JustWatch attribution.
-- **Keep adult content private by default** with local age confirmation, a six-digit device PIN, and five-attempt lockout; companion and public surfaces never receive it.
+- **Keep adult content private by default** with local age confirmation, a six-digit device PIN, and five-attempt lockout. The gate partitions Search, External ID, Title, Person, Collection, Company, Network, Keyword, Credit Detail, recommendations and similar titles; every client filters again before display, while companion and public surfaces never receive restricted titles.
 - **Connect TMDb safely** through browser approval or TV QR without entering a password in SmartMovie. Browse paginated Movie/TV account recommendations, rate Movie/TV/Episode titles, and manage account library/lists with durable offline mutation retry.
 - **Manage mixed custom lists** by loading every list page, editing metadata, paging through Movie/TV contents, searching the catalog, and adding or removing titles with restart-safe optimistic synchronization.
 - **Build a local-first library** with independent Favorite and Watchlist actions. SwiftData keeps both readable offline; private CloudKit remains an Apple storage option.
@@ -205,7 +205,7 @@ cd ../..
 ./scripts/verify-release.sh
 ```
 
-The current verified local baseline contains 66 Swift tests and 93 Worker tests. Coverage includes canonical `/v1` and `/v2` fixture decoding, deterministic catalog-review and recommendation presentation, non-empty editorial and Movie/TV/Season/Episode media fixtures, image/video/external-ID presentation, numeric TMDb Season/Episode external-ID normalization, typed regional release/content-rating, Movie/TV alternative-title and translation metadata, configured capability/fixture equality, fail-closed browser/TV account rollout, malformed broker configuration and return-URI allowlists, cold-start callback deferral, stale completion invalidation, durable outbox isolation, capability-gated Advanced Discover and Profile provider regions with a fail-closed `/v1` fallback, complete Movie/TV Discover queries and regional provider configuration, External ID and Credit Detail source/path mapping, account recommendations, normalized/paginated custom mixed lists, restart-safe pending item snapshots, explicit adult age confirmation, six-digit PIN validation, five-attempt lockout, local adult filtering and in-flight request invalidation, metadata/item mutations, normalized person/title credit links, exact episode companion context, unknown and missing nullable fields, success/error schema validation, repeatable D1 migrations, encryption/callback/CSRF controls, durable idempotency, TMDb Changes pagination/backlog recovery, invalid cursor recovery, verified changing-page-count fallback, D1 parameter-bound chunking, monotonic revision and cache-bypass behavior, retries, cancellation, pagination, and data behavior without live personal credentials.
+The current verified local baseline contains 67 Swift tests and 96 Worker tests. Coverage includes canonical `/v1` and `/v2` fixture decoding, deterministic catalog-review and recommendation presentation, non-empty editorial and Movie/TV/Season/Episode media fixtures, image/video/external-ID presentation, numeric TMDb Season/Episode external-ID normalization, typed regional release/content-rating, Movie/TV alternative-title and translation metadata, configured capability/fixture equality, fail-closed browser/TV account rollout, malformed broker configuration and return-URI allowlists, cold-start callback deferral, stale completion invalidation, durable outbox isolation, capability-gated Advanced Discover and Profile provider regions with a fail-closed `/v1` fallback, complete Movie/TV Discover queries and regional provider configuration, External ID and Credit Detail source/path mapping, account recommendations, normalized/paginated custom mixed lists, restart-safe pending item snapshots, explicit adult age confirmation, six-digit PIN validation, five-attempt lockout, Worker partitioning plus client-side fail-closed filtering for every entity-related title/credit surface, local adult filtering and in-flight request invalidation, metadata/item mutations, normalized person/title credit links, exact episode companion context, unknown and missing nullable fields, success/error schema validation, repeatable D1 migrations, encryption/callback/CSRF controls, durable idempotency, TMDb Changes pagination/backlog recovery, invalid cursor recovery, verified changing-page-count fallback, D1 parameter-bound chunking, monotonic revision and cache-bypass behavior, retries, cancellation, pagination, and data behavior without live personal credentials.
 
 CI independently builds and analyzes iOS, iPad/Catalyst, tvOS, native macOS, watchOS, and visionOS, then installs and launches the iOS app in Simulator. Read [Testing](docs/TESTING.md) for destination-specific commands and the manual device matrix.
 

SmartMovieKit/Sources/SmartMovieKit/App/FeatureModels.swift

@@ -356,7 +356,7 @@ public final class SearchViewModel {
                       query.trimmingCharacters(in: .whitespacesAndNewlines) == expectedQuery,
                       scope == expectedScope,
                       entityScope == expectedEntityScope else { return }
-                entities = result.results
+                entities = result.results.applyingAdultVisibility(includeAdult: includeAdult)
                 page = result.page
                 canLoadMore = result.page < result.totalPages
                 isLoading = false
@@ -393,15 +393,16 @@ public final class SearchViewModel {
                 let result = try await catalogV2.findExternalID(
                     externalID,
                     source: expectedSource,
-                    language: language
+                    language: language,
+                    includeAdult: includeAdult
                 )
                 guard !Task.isCancelled,
                       searchGeneration == expectedGeneration,
                       self.includeAdult == includeAdult,
                       mode == .externalID,
                       query.trimmingCharacters(in: .whitespacesAndNewlines) == externalID,
                       externalIDSource == expectedSource else { return }
-                entities = result.results.filter { includeAdult || !$0.isAdultTitle }
+                entities = result.results.applyingAdultVisibility(includeAdult: includeAdult)
                 isLoading = false
             } catch is CancellationError {
                 return
@@ -472,7 +473,7 @@ public final class SearchViewModel {
                       query.trimmingCharacters(in: .whitespacesAndNewlines) == expectedQuery,
                       scope == expectedScope,
                       entityScope == expectedEntityScope else { return }
-                entities.append(contentsOf: result.results.filter { incoming in
+                entities.append(contentsOf: result.results.applyingAdultVisibility(includeAdult: includeAdult).filter { incoming in
                     !entities.contains(where: { $0.id == incoming.id })
                 })
                 page = result.page
@@ -487,13 +488,12 @@ public final class SearchViewModel {
             }
         }
     }
-
     public func applyAdultVisibility(includeAdult: Bool) {
         self.includeAdult = includeAdult
         guard !includeAdult else { return }
         searchTask?.cancel()
         searchGeneration += 1
-        entities.removeAll(where: \.isAdultTitle)
+        entities = entities.applyingAdultVisibility(includeAdult: false)
         isLoading = false
         canLoadMore = false
     }

SmartMovieKit/Sources/SmartMovieKit/Data/CatalogRepositoryV2.swift

@@ -40,11 +40,13 @@ extension RemoteCatalogRepository: CatalogV2Repository {
     public func findExternalID(
         _ externalID: String,
         source: ExternalIDSource,
-        language: String
+        language: String,
+        includeAdult: Bool
     ) async throws -> ExternalIDFindResult {
         try await client.get("v2/find/\(externalID)", queryItems: [
             URLQueryItem(name: "source", value: source.rawValue),
-            URLQueryItem(name: "language", value: language)
+            URLQueryItem(name: "language", value: language),
+            URLQueryItem(name: "include_adult", value: String(includeAdult))
         ])
     }
 
@@ -63,26 +65,40 @@ extension RemoteCatalogRepository: CatalogV2Repository {
         return try await client.get("v2/titles/\(mediaType.rawValue)/\(id)", queryItems: queryItems)
     }
 
-    public func person(id: Int, language: String) async throws -> PersonDetail {
-        try await client.get("v2/entities/person/\(id)", queryItems: [URLQueryItem(name: "language", value: language)])
+    public func person(id: Int, language: String, includeAdult: Bool) async throws -> PersonDetail {
+        try await client.get("v2/entities/person/\(id)", queryItems: [
+            URLQueryItem(name: "language", value: language),
+            URLQueryItem(name: "include_adult", value: String(includeAdult))
+        ])
     }
 
-    public func collection(id: Int, language: String) async throws -> CollectionDetail {
-        try await client.get("v2/entities/collection/\(id)", queryItems: [URLQueryItem(name: "language", value: language)])
+    public func collection(id: Int, language: String, includeAdult: Bool) async throws -> CollectionDetail {
+        try await client.get("v2/entities/collection/\(id)", queryItems: [
+            URLQueryItem(name: "language", value: language),
+            URLQueryItem(name: "include_adult", value: String(includeAdult))
+        ])
     }
 
-    public func organization(kind: EntityKind, id: Int, language: String, page: Int) async throws -> OrganizationDetail {
+    public func organization(
+        kind: EntityKind,
+        id: Int,
+        language: String,
+        page: Int,
+        includeAdult: Bool
+    ) async throws -> OrganizationDetail {
         guard kind == .company || kind == .network else { throw APIError.notFound }
         return try await client.get("v2/entities/\(kind.rawValue)/\(id)", queryItems: [
             URLQueryItem(name: "language", value: language),
-            URLQueryItem(name: "page", value: String(page))
+            URLQueryItem(name: "page", value: String(page)),
+            URLQueryItem(name: "include_adult", value: String(includeAdult))
         ])
     }
 
-    public func keyword(id: Int, language: String, page: Int) async throws -> KeywordDetail {
+    public func keyword(id: Int, language: String, page: Int, includeAdult: Bool) async throws -> KeywordDetail {
         try await client.get("v2/entities/keyword/\(id)", queryItems: [
             URLQueryItem(name: "language", value: language),
-            URLQueryItem(name: "page", value: String(page))
+            URLQueryItem(name: "page", value: String(page)),
+            URLQueryItem(name: "include_adult", value: String(includeAdult))
         ])
     }
 
@@ -97,10 +113,13 @@ extension RemoteCatalogRepository: CatalogV2Repository {
         )
     }
 
-    public func credit(id: String, language: String) async throws -> CreditDetail {
+    public func credit(id: String, language: String, includeAdult: Bool) async throws -> CreditDetail {
         try await client.get(
             "v2/credits/\(id)",
-            queryItems: [URLQueryItem(name: "language", value: language)]
+            queryItems: [
+                URLQueryItem(name: "language", value: language),
+                URLQueryItem(name: "include_adult", value: String(includeAdult))
+            ]
         )
     }
 }

SmartMovieKit/Sources/SmartMovieKit/Domain/CatalogEntity+Adult.swift

@@ -3,4 +3,40 @@ extension CatalogEntity {
         if case .title(let title) = self { return title.isAdult }
         return false
     }
+
+    func applyingAdultVisibility(includeAdult: Bool) -> CatalogEntity? {
+        switch self {
+        case .title(let title):
+            return includeAdult || !title.isAdult ? self : nil
+        case .person(let person):
+            return .person(PersonSummary(
+                id: person.id,
+                name: person.name,
+                profilePath: person.profilePath,
+                knownForDepartment: person.knownForDepartment,
+                popularity: person.popularity,
+                knownFor: person.knownFor.filter { includeAdult || !$0.isAdult }
+            ))
+        case .season, .episode:
+            return includeAdult ? self : nil
+        default:
+            return self
+        }
+    }
+}
+
+extension Array where Element == CatalogEntity {
+    func applyingAdultVisibility(includeAdult: Bool) -> [CatalogEntity] {
+        compactMap { $0.applyingAdultVisibility(includeAdult: includeAdult) }
+    }
+}
+
+public enum CatalogAdultVisibility {
+    public static func titles(_ values: [TitleSummary], includeAdult: Bool) -> [TitleSummary] {
+        values.filter { includeAdult || !$0.isAdult }
+    }
+
+    public static func credits(_ values: [Credit], includeAdult: Bool) -> [Credit] {
+        values.filter { includeAdult || $0.adult != true }
+    }
 }

SmartMovieKit/Sources/SmartMovieKit/Domain/CreditDetailModels.swift

@@ -8,6 +8,18 @@ public struct CreditDetail: Codable, Hashable, Sendable {
     public let character: String?
     public let personSummary: PersonSummary?
     public let titleSummary: TitleSummary?
+
+    public func applyingAdultVisibility(includeAdult: Bool) -> CreditDetail {
+        CreditDetail(
+            creditId: creditId,
+            creditType: creditType,
+            department: department,
+            job: job,
+            character: character,
+            personSummary: personSummary,
+            titleSummary: titleSummary.flatMap { includeAdult || !$0.isAdult ? $0 : nil }
+        )
+    }
 }
 
 public extension Credit {

SmartMovieKit/Sources/SmartMovieKit/Domain/ModelsV2.swift

@@ -223,6 +223,7 @@ public struct Credit: Codable, Hashable, Sendable {
     public let posterPath: String?
     public let order: Int?
     public let episodeCount: Int?
+    public let adult: Bool?
 }
 
 public struct ImageAsset: Codable, Hashable, Sendable {

SmartMovieKit/Sources/SmartMovieKit/Domain/RepositoryProtocolsV2.swift

@@ -11,21 +11,32 @@ public protocol CatalogV2Repository: Sendable {
         includeAdult: Bool
     ) async throws -> PagedResult<CatalogEntity>
     func searchEntities(_ request: EntitySearchRequest) async throws -> PagedResult<CatalogEntity>
-    func findExternalID(_ externalID: String, source: ExternalIDSource, language: String) async throws -> ExternalIDFindResult
+    func findExternalID(
+        _ externalID: String,
+        source: ExternalIDSource,
+        language: String,
+        includeAdult: Bool
+    ) async throws -> ExternalIDFindResult
     func deepDetail(
         mediaType: MediaType,
         id: Int,
         language: String,
         region: String?,
         includeAdult: Bool
     ) async throws -> TitleDetailV2
-    func person(id: Int, language: String) async throws -> PersonDetail
-    func collection(id: Int, language: String) async throws -> CollectionDetail
-    func organization(kind: EntityKind, id: Int, language: String, page: Int) async throws -> OrganizationDetail
-    func keyword(id: Int, language: String, page: Int) async throws -> KeywordDetail
+    func person(id: Int, language: String, includeAdult: Bool) async throws -> PersonDetail
+    func collection(id: Int, language: String, includeAdult: Bool) async throws -> CollectionDetail
+    func organization(
+        kind: EntityKind,
+        id: Int,
+        language: String,
+        page: Int,
+        includeAdult: Bool
+    ) async throws -> OrganizationDetail
+    func keyword(id: Int, language: String, page: Int, includeAdult: Bool) async throws -> KeywordDetail
     func season(seriesID: Int, number: Int, language: String) async throws -> SeasonDetail
     func episode(seriesID: Int, season: Int, number: Int, language: String) async throws -> EpisodeDetail
-    func credit(id: String, language: String) async throws -> CreditDetail
+    func credit(id: String, language: String, includeAdult: Bool) async throws -> CreditDetail
 }
 
 public protocol AccountRecommendationsLoading: Sendable {

SmartMovieKit/Sources/SmartMovieKit/Resources/en.lproj/Localizable.strings

@@ -144,7 +144,7 @@
 "Translations" = "Translations";
 "External identifiers" = "External identifiers";
 "Source repositories" = "Source repositories";
-"Catalog metadata description" = "Explore TMDb image and video galleries, member reviews, catalog recommendations, regional release dates, certifications, localized titles, translations and external identifiers across titles, seasons and episodes.";
+"Catalog metadata description" = "Explore TMDb image and video galleries, member reviews, recommendations, regional release dates, certifications, localized titles, translations and external identifiers. The local adult-content PIN applies to Search and every related Person, Collection, Company, Network, Keyword and Credit Detail surface.";
 "Details" = "Details";
 "Images" = "Images";
 "Catalog image" = "TMDb catalog image";

SmartMovieKit/Sources/SmartMovieKit/Resources/ja.lproj/Localizable.strings

@@ -144,7 +144,7 @@
 "Translations" = "翻訳";
 "External identifiers" = "外部識別子";
 "Source repositories" = "ソースリポジトリ";
-"Catalog metadata description" = "作品、シーズン、エピソードのTMDb画像・動画ギャラリー、レビュー、おすすめ、地域別公開日、年齢区分、ローカライズされたタイトル、翻訳、外部識別子を確認できます。";
+"Catalog metadata description" = "TMDbの画像、動画、レビュー、おすすめ、公開情報、ローカライズ、外部識別子を確認できます。端末内の成人向けPINは、検索と人物、コレクション、会社、ネットワーク、キーワード、クレジット詳細の関連画面すべてに適用されます。";
 "Details" = "詳細";
 "Images" = "画像";
 "Catalog image" = "TMDbカタログ画像";

SmartMovieKit/Sources/SmartMovieKit/Resources/ko.lproj/Localizable.strings

@@ -144,7 +144,7 @@
 "Translations" = "번역";
 "External identifiers" = "외부 식별자";
 "Source repositories" = "소스 저장소";
-"Catalog metadata description" = "작품, 시즌, 에피소드의 TMDb 이미지·동영상 갤러리, 리뷰, 추천, 지역별 공개일, 시청 등급, 현지화 제목, 번역 및 외부 식별자를 확인하세요.";
+"Catalog metadata description" = "TMDb 이미지, 동영상, 리뷰, 추천, 공개 정보, 현지화 및 외부 식별자를 확인하세요. 기기 내 성인 콘텐츠 PIN은 검색과 인물, 컬렉션, 제작사, 네트워크, 키워드 및 크레딧 상세의 모든 관련 화면에 적용됩니다.";
 "Details" = "세부 정보";
 "Images" = "이미지";
 "Catalog image" = "TMDb 카탈로그 이미지";