@dvai-bridge/ios 4.0.0 → 4.0.1

package/ios/Sources/DVAIBridge/License/Audience.swift

@@ -1,133 +1,133 @@
-/*
- * Runtime audience + platform + dev-mode detection for the iOS SDK.
- *
- * Mirrors `packages/dvai-bridge-core/src/license/audience.ts`. The
- * semantics are identical; only the platform APIs differ.
- *
- *   - audience  = `Bundle.main.bundleIdentifier` (may be `nil` in some
- *                 unit-test hosts; null is treated like the JS side does
- *                 — only `"*"` aud entries match)
- *   - platform  = always `.ios` from this SDK (the Capacitor consumers
- *                 use the Capacitor SDK, which detects `.capacitor`
- *                 from JS-side; this iOS SDK is for native iOS apps)
- *   - dev mode  = DEBUG build OR simulator OR DVAI_FORCE_DEV=1
- *                 (DVAI_FORCE_PROD=1 overrides DEBUG / simulator)
- */
-import Foundation
-
-/// Detect the current SDK platform identifier. Always `.ios` on iOS —
-/// Capacitor consumers use a different SDK (the Capacitor plugin's
-/// JS-side validator detects `capacitor`). React Native consumers
-/// likewise use a different SDK.
-public func detectPlatform() -> DvaiPlatform {
-    return .ios
-}
-
-/// Read an environment variable via C's `getenv` so we observe live
-/// updates (`setenv` in tests). `ProcessInfo.environment` caches its
-/// dict on Apple's Foundation, which makes per-test env mutation
-/// unreliable.
-internal func envVar(_ name: String) -> String? {
-    guard let cstr = getenv(name) else { return nil }
-    let value = String(cString: cstr)
-    return value.isEmpty ? nil : value
-}
-
-/// Detect the current audience string the license must bind. On iOS
-/// this is the running app's bundle identifier (e.g. `"com.acme.app"`).
-///
-/// Returns `nil` only when no bundle identifier is available — uncommon
-/// in production, but possible in some SwiftPM test hosts. Null is
-/// handled by the validator: it matches only the `"*"` aud entry.
-///
-/// An explicit `DVAI_AUDIENCE` environment variable overrides the bundle
-/// id (matches the JS-side override; mostly useful for tests).
-public func detectAudience() -> String? {
-    if let override = envVar("DVAI_AUDIENCE") {
-        return override
-    }
-    if let bundleId = Bundle.main.bundleIdentifier, !bundleId.isEmpty {
-        return bundleId
-    }
-    return nil
-}
-
-/// Detect whether the SDK is running in a developer environment where
-/// license enforcement should be bypassed. The bypass list is
-/// intentionally generous: blocking a developer mid-Xcode-run with a
-/// license-not-found error would be hostile.
-///
-/// Order (first match wins):
-///   1. `DVAI_FORCE_PROD=1` → force production (overrides DEBUG +
-///      simulator). The host app's CI sets this to exercise license
-///      enforcement in non-RELEASE builds.
-///   2. `DVAI_FORCE_DEV=1` → force dev. Explicit operator opt-in.
-///   3. `#if DEBUG` → dev. Compile-time check — the DEBUG configuration
-///      bypasses licensing entirely so the in-Xcode dev loop never
-///      surfaces a license error.
-///   4. `targetEnvironment(simulator)` → dev. Same intent: a simulator
-///      run is by construction a dev environment.
-///   5. otherwise → production, license required.
-public func detectDevMode() -> (isDev: Bool, reason: String) {
-    // 1. Explicit env-var overrides (operator-level, runtime). Use
-    //    `envVar` (libc getenv) so DVAI_FORCE_* mutated mid-process —
-    //    e.g. by tests — is picked up.
-    let forceProd = envVar("DVAI_FORCE_PROD")
-    if forceProd == "1" || forceProd == "true" {
-        return (false, "DVAI_FORCE_PROD set")
-    }
-    let forceDev = envVar("DVAI_FORCE_DEV")
-    if forceDev == "1" || forceDev == "true" {
-        return (true, "DVAI_FORCE_DEV set")
-    }
-
-    // 2. DEBUG configuration.
-    #if DEBUG
-    return (true, "DEBUG build configuration")
-    #else
-    // 3. Simulator (DEBUG would have already caught most simulator
-    //    runs; this branch matters for a Release-configuration build
-    //    happening to run on the simulator — rare, but harmless to
-    //    bypass).
-    #if targetEnvironment(simulator)
-    return (true, "iOS Simulator")
-    #else
-    return (false, "production-class environment")
-    #endif
-    #endif
-}
-
-/// Decide whether a license-payload `aud` entry matches the current
-/// runtime audience. Supports exact match and `*.example.com` wildcard
-/// matching for subdomain (here: bundle-id-suffix) binding. Returns
-/// the matched `aud` pattern on success so it can be recorded for
-/// audit, or `nil` on miss.
-///
-/// Match rules (identical to the JS-side `matchAudience`):
-///   - `"foo"` matches `"foo"` exactly (case-insensitive)
-///   - `"*.example.com"` matches `"example.com"` AND any
-///     `"<sub>.example.com"`
-///   - `"*"` matches any non-nil audience (intentionally permissive;
-///     used for trial / site licenses that span all of a customer's
-///     deployments)
-///
-/// A `nil` runtime audience matches only `"*"` entries — a build with
-/// no bundle identifier can activate any-domain licenses but not
-/// bundle-bound ones.
-public func matchAudience(runtimeAudience: String?, audClaim: [String]) -> String? {
-    guard let runtime = runtimeAudience?.lowercased(), !runtime.isEmpty else {
-        return audClaim.contains("*") ? "*" : nil
-    }
-    for pattern in audClaim {
-        let p = pattern.lowercased()
-        if p == "*" { return pattern }            // permissive wildcard
-        if p == runtime { return pattern }        // exact match
-        if p.hasPrefix("*.") {
-            let suffix = String(p.dropFirst(2))
-            if runtime == suffix || runtime.hasSuffix("." + suffix) {
-                return pattern
-            }
-        }
-    }
-    return nil
-}
+/*
+ * Runtime audience + platform + dev-mode detection for the iOS SDK.
+ *
+ * Mirrors `packages/dvai-bridge-core/src/license/audience.ts`. The
+ * semantics are identical; only the platform APIs differ.
+ *
+ *   - audience  = `Bundle.main.bundleIdentifier` (may be `nil` in some
+ *                 unit-test hosts; null is treated like the JS side does
+ *                 — only `"*"` aud entries match)
+ *   - platform  = always `.ios` from this SDK (the Capacitor consumers
+ *                 use the Capacitor SDK, which detects `.capacitor`
+ *                 from JS-side; this iOS SDK is for native iOS apps)
+ *   - dev mode  = DEBUG build OR simulator OR DVAI_FORCE_DEV=1
+ *                 (DVAI_FORCE_PROD=1 overrides DEBUG / simulator)
+ */
+import Foundation
+
+/// Detect the current SDK platform identifier. Always `.ios` on iOS —
+/// Capacitor consumers use a different SDK (the Capacitor plugin's
+/// JS-side validator detects `capacitor`). React Native consumers
+/// likewise use a different SDK.
+public func detectPlatform() -> DvaiPlatform {
+    return .ios
+}
+
+/// Read an environment variable via C's `getenv` so we observe live
+/// updates (`setenv` in tests). `ProcessInfo.environment` caches its
+/// dict on Apple's Foundation, which makes per-test env mutation
+/// unreliable.
+internal func envVar(_ name: String) -> String? {
+    guard let cstr = getenv(name) else { return nil }
+    let value = String(cString: cstr)
+    return value.isEmpty ? nil : value
+}
+
+/// Detect the current audience string the license must bind. On iOS
+/// this is the running app's bundle identifier (e.g. `"com.acme.app"`).
+///
+/// Returns `nil` only when no bundle identifier is available — uncommon
+/// in production, but possible in some SwiftPM test hosts. Null is
+/// handled by the validator: it matches only the `"*"` aud entry.
+///
+/// An explicit `DVAI_AUDIENCE` environment variable overrides the bundle
+/// id (matches the JS-side override; mostly useful for tests).
+public func detectAudience() -> String? {
+    if let override = envVar("DVAI_AUDIENCE") {
+        return override
+    }
+    if let bundleId = Bundle.main.bundleIdentifier, !bundleId.isEmpty {
+        return bundleId
+    }
+    return nil
+}
+
+/// Detect whether the SDK is running in a developer environment where
+/// license enforcement should be bypassed. The bypass list is
+/// intentionally generous: blocking a developer mid-Xcode-run with a
+/// license-not-found error would be hostile.
+///
+/// Order (first match wins):
+///   1. `DVAI_FORCE_PROD=1` → force production (overrides DEBUG +
+///      simulator). The host app's CI sets this to exercise license
+///      enforcement in non-RELEASE builds.
+///   2. `DVAI_FORCE_DEV=1` → force dev. Explicit operator opt-in.
+///   3. `#if DEBUG` → dev. Compile-time check — the DEBUG configuration
+///      bypasses licensing entirely so the in-Xcode dev loop never
+///      surfaces a license error.
+///   4. `targetEnvironment(simulator)` → dev. Same intent: a simulator
+///      run is by construction a dev environment.
+///   5. otherwise → production, license required.
+public func detectDevMode() -> (isDev: Bool, reason: String) {
+    // 1. Explicit env-var overrides (operator-level, runtime). Use
+    //    `envVar` (libc getenv) so DVAI_FORCE_* mutated mid-process —
+    //    e.g. by tests — is picked up.
+    let forceProd = envVar("DVAI_FORCE_PROD")
+    if forceProd == "1" || forceProd == "true" {
+        return (false, "DVAI_FORCE_PROD set")
+    }
+    let forceDev = envVar("DVAI_FORCE_DEV")
+    if forceDev == "1" || forceDev == "true" {
+        return (true, "DVAI_FORCE_DEV set")
+    }
+
+    // 2. DEBUG configuration.
+    #if DEBUG
+    return (true, "DEBUG build configuration")
+    #else
+    // 3. Simulator (DEBUG would have already caught most simulator
+    //    runs; this branch matters for a Release-configuration build
+    //    happening to run on the simulator — rare, but harmless to
+    //    bypass).
+    #if targetEnvironment(simulator)
+    return (true, "iOS Simulator")
+    #else
+    return (false, "production-class environment")
+    #endif
+    #endif
+}
+
+/// Decide whether a license-payload `aud` entry matches the current
+/// runtime audience. Supports exact match and `*.example.com` wildcard
+/// matching for subdomain (here: bundle-id-suffix) binding. Returns
+/// the matched `aud` pattern on success so it can be recorded for
+/// audit, or `nil` on miss.
+///
+/// Match rules (identical to the JS-side `matchAudience`):
+///   - `"foo"` matches `"foo"` exactly (case-insensitive)
+///   - `"*.example.com"` matches `"example.com"` AND any
+///     `"<sub>.example.com"`
+///   - `"*"` matches any non-nil audience (intentionally permissive;
+///     used for trial / site licenses that span all of a customer's
+///     deployments)
+///
+/// A `nil` runtime audience matches only `"*"` entries — a build with
+/// no bundle identifier can activate any-domain licenses but not
+/// bundle-bound ones.
+public func matchAudience(runtimeAudience: String?, audClaim: [String]) -> String? {
+    guard let runtime = runtimeAudience?.lowercased(), !runtime.isEmpty else {
+        return audClaim.contains("*") ? "*" : nil
+    }
+    for pattern in audClaim {
+        let p = pattern.lowercased()
+        if p == "*" { return pattern }            // permissive wildcard
+        if p == runtime { return pattern }        // exact match
+        if p.hasPrefix("*.") {
+            let suffix = String(p.dropFirst(2))
+            if runtime == suffix || runtime.hasSuffix("." + suffix) {
+                return pattern
+            }
+        }
+    }
+    return nil
+}

package/ios/Sources/DVAIBridge/License/Discovery.swift

@@ -1,164 +1,164 @@
-/*
- * License-file discovery for the iOS SDK.
- *
- * Mirrors `packages/dvai-bridge-core/src/license/discovery.ts` but with
- * iOS-native locations (Bundle resources, Documents directory, App Group
- * containers) in place of the JS side's CWD-based filesystem walk.
- *
- * Priority order (first hit wins):
- *
- *   1. `LicenseDiscoveryOptions.token` — inline JWT string. Useful when
- *      the host app fetches its license over the network at runtime
- *      and wants to inject the result without touching disk.
- *
- *   2. `LicenseDiscoveryOptions.path` — explicit file path. Useful for
- *      tests or for hosts that store the .jwt outside the standard
- *      locations. If this path is set but the file isn't there or
- *      isn't readable, this is a real miss (we do NOT silently fall
- *      through to auto-discovery) — same semantics as the JS side.
- *
- *   3. `DVAI_LICENSE_PATH` env var. Operator-supplied path; helpful
- *      for CI / TestFlight where you don't want to ship the .jwt in
- *      the bundle. Misses fall through to (5).
- *
- *   4. `DVAI_LICENSE_TOKEN` env var. Inline JWT in the environment.
- *
- *   5. `dvai-license.jwt` resource in `Bundle.main`. The dev-friendly
- *      happy path: add the file to the app's "Copy Bundle Resources"
- *      phase, the SDK picks it up automatically.
- *
- *   6. `Application Support/dvai-bridge/dvai-license.jwt` in the app's
- *      sandbox. Useful for licenses fetched after install (e.g. via
- *      an in-app purchase flow).
- *
- *   7. `Documents/dvai-license.jwt`. Last-resort fallback — visible
- *      via iTunes File Sharing if the app opts in, so handy for
- *      side-loading a license during development.
- *
- * Returning `nil` means "no license token found"; the validator treats
- * that as the free-tier case (after the dev-mode bypass).
- */
-import Foundation
-
-/// Default filename the SDK looks for in Bundle / Documents / App Support.
-/// Chosen to be self-documenting and to encourage commit-to-vcs (so the
-/// license travels with the code).
-public let DVAI_DEFAULT_LICENSE_FILENAME = "dvai-license.jwt"
-
-public struct LicenseDiscoveryOptions: Sendable {
-    /// Pre-loaded JWT string (skips all filesystem lookups).
-    public var token: String?
-    /// Explicit path to load from. Overrides auto-discovery.
-    public var path: String?
-    /// App Group identifier to also search (e.g. for shared licenses
-    /// across an app + extension). Optional; default `nil` skips the
-    /// App Group lookup.
-    public var appGroupIdentifier: String?
-
-    public init(
-        token: String? = nil,
-        path: String? = nil,
-        appGroupIdentifier: String? = nil
-    ) {
-        self.token = token
-        self.path = path
-        self.appGroupIdentifier = appGroupIdentifier
-    }
-}
-
-/// Best-effort load of a license JWT. Returns the raw token string +
-/// source description on success, or nil on miss. Errors during loading
-/// (file not found, permission denied) collapse to nil — the
-/// validator's responsibility is to handle the no-license case
-/// gracefully, not the discovery layer's.
-///
-/// Source descriptions are surfaced in `LicenseStatus.freeProd.reason`
-/// for debug, and shown in dashboards so the developer can see which
-/// of the seven locations resolved.
-public func discoverLicenseToken(
-    options: LicenseDiscoveryOptions = LicenseDiscoveryOptions()
-) -> (token: String, source: String)? {
-    // 1. Explicit token wins.
-    if let token = options.token, !token.isEmpty {
-        return (token.trimmingCharacters(in: .whitespacesAndNewlines), "options.token")
-    }
-
-    // 2. Explicit path.
-    if let path = options.path, !path.isEmpty {
-        if let loaded = tryLoadFromPath(path) {
-            return (loaded, path)
-        }
-        return nil // explicit miss — do NOT fall through
-    }
-
-    // 3. Env-var path. Use `envVar` (libc getenv) so DVAI_LICENSE_PATH
-    //    mutated mid-process — e.g. by tests — is picked up.
-    if let envPath = envVar("DVAI_LICENSE_PATH") {
-        if let loaded = tryLoadFromPath(envPath) {
-            return (loaded, "DVAI_LICENSE_PATH=\(envPath)")
-        }
-    }
-
-    // 4. Env-var inline token.
-    if let envToken = envVar("DVAI_LICENSE_TOKEN") {
-        return (
-            envToken.trimmingCharacters(in: .whitespacesAndNewlines),
-            "DVAI_LICENSE_TOKEN env var"
-        )
-    }
-
-    // 5. Bundle resource (dvai-license.jwt next to the app's other
-    //    bundled resources).
-    if let bundleURL = Bundle.main.url(forResource: "dvai-license", withExtension: "jwt") {
-        if let loaded = tryLoadFromPath(bundleURL.path) {
-            return (loaded, "Bundle.main resource dvai-license.jwt")
-        }
-    }
-
-    // 6. Application Support / dvai-bridge / dvai-license.jwt.
-    if let appSupportURL = (try? FileManager.default.url(
-        for: .applicationSupportDirectory,
-        in: .userDomainMask,
-        appropriateFor: nil,
-        create: false
-    )) {
-        let candidate = appSupportURL
-            .appendingPathComponent("dvai-bridge", isDirectory: true)
-            .appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME)
-        if let loaded = tryLoadFromPath(candidate.path) {
-            return (loaded, candidate.path)
-        }
-    }
-
-    // 7. Documents directory.
-    if let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first {
-        let candidate = docsURL.appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME)
-        if let loaded = tryLoadFromPath(candidate.path) {
-            return (loaded, candidate.path)
-        }
-    }
-
-    // 8. (Optional) App Group container, if configured.
-    if let groupId = options.appGroupIdentifier, !groupId.isEmpty {
-        if let groupURL = FileManager.default
-            .containerURL(forSecurityApplicationGroupIdentifier: groupId)?
-            .appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME) {
-            if let loaded = tryLoadFromPath(groupURL.path) {
-                return (loaded, groupURL.path)
-            }
-        }
-    }
-
-    return nil
-}
-
-/// Read a file at `path` and return its trimmed UTF-8 contents, or
-/// nil on any error (missing / permission / encoding).
-private func tryLoadFromPath(_ path: String) -> String? {
-    let fm = FileManager.default
-    guard fm.fileExists(atPath: path) else { return nil }
-    guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else { return nil }
-    guard let text = String(data: data, encoding: .utf8) else { return nil }
-    let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
-    return trimmed.isEmpty ? nil : trimmed
-}
+/*
+ * License-file discovery for the iOS SDK.
+ *
+ * Mirrors `packages/dvai-bridge-core/src/license/discovery.ts` but with
+ * iOS-native locations (Bundle resources, Documents directory, App Group
+ * containers) in place of the JS side's CWD-based filesystem walk.
+ *
+ * Priority order (first hit wins):
+ *
+ *   1. `LicenseDiscoveryOptions.token` — inline JWT string. Useful when
+ *      the host app fetches its license over the network at runtime
+ *      and wants to inject the result without touching disk.
+ *
+ *   2. `LicenseDiscoveryOptions.path` — explicit file path. Useful for
+ *      tests or for hosts that store the .jwt outside the standard
+ *      locations. If this path is set but the file isn't there or
+ *      isn't readable, this is a real miss (we do NOT silently fall
+ *      through to auto-discovery) — same semantics as the JS side.
+ *
+ *   3. `DVAI_LICENSE_PATH` env var. Operator-supplied path; helpful
+ *      for CI / TestFlight where you don't want to ship the .jwt in
+ *      the bundle. Misses fall through to (5).
+ *
+ *   4. `DVAI_LICENSE_TOKEN` env var. Inline JWT in the environment.
+ *
+ *   5. `dvai-license.jwt` resource in `Bundle.main`. The dev-friendly
+ *      happy path: add the file to the app's "Copy Bundle Resources"
+ *      phase, the SDK picks it up automatically.
+ *
+ *   6. `Application Support/dvai-bridge/dvai-license.jwt` in the app's
+ *      sandbox. Useful for licenses fetched after install (e.g. via
+ *      an in-app purchase flow).
+ *
+ *   7. `Documents/dvai-license.jwt`. Last-resort fallback — visible
+ *      via iTunes File Sharing if the app opts in, so handy for
+ *      side-loading a license during development.
+ *
+ * Returning `nil` means "no license token found"; the validator treats
+ * that as the free-tier case (after the dev-mode bypass).
+ */
+import Foundation
+
+/// Default filename the SDK looks for in Bundle / Documents / App Support.
+/// Chosen to be self-documenting and to encourage commit-to-vcs (so the
+/// license travels with the code).
+public let DVAI_DEFAULT_LICENSE_FILENAME = "dvai-license.jwt"
+
+public struct LicenseDiscoveryOptions: Sendable {
+    /// Pre-loaded JWT string (skips all filesystem lookups).
+    public var token: String?
+    /// Explicit path to load from. Overrides auto-discovery.
+    public var path: String?
+    /// App Group identifier to also search (e.g. for shared licenses
+    /// across an app + extension). Optional; default `nil` skips the
+    /// App Group lookup.
+    public var appGroupIdentifier: String?
+
+    public init(
+        token: String? = nil,
+        path: String? = nil,
+        appGroupIdentifier: String? = nil
+    ) {
+        self.token = token
+        self.path = path
+        self.appGroupIdentifier = appGroupIdentifier
+    }
+}
+
+/// Best-effort load of a license JWT. Returns the raw token string +
+/// source description on success, or nil on miss. Errors during loading
+/// (file not found, permission denied) collapse to nil — the
+/// validator's responsibility is to handle the no-license case
+/// gracefully, not the discovery layer's.
+///
+/// Source descriptions are surfaced in `LicenseStatus.freeProd.reason`
+/// for debug, and shown in dashboards so the developer can see which
+/// of the seven locations resolved.
+public func discoverLicenseToken(
+    options: LicenseDiscoveryOptions = LicenseDiscoveryOptions()
+) -> (token: String, source: String)? {
+    // 1. Explicit token wins.
+    if let token = options.token, !token.isEmpty {
+        return (token.trimmingCharacters(in: .whitespacesAndNewlines), "options.token")
+    }
+
+    // 2. Explicit path.
+    if let path = options.path, !path.isEmpty {
+        if let loaded = tryLoadFromPath(path) {
+            return (loaded, path)
+        }
+        return nil // explicit miss — do NOT fall through
+    }
+
+    // 3. Env-var path. Use `envVar` (libc getenv) so DVAI_LICENSE_PATH
+    //    mutated mid-process — e.g. by tests — is picked up.
+    if let envPath = envVar("DVAI_LICENSE_PATH") {
+        if let loaded = tryLoadFromPath(envPath) {
+            return (loaded, "DVAI_LICENSE_PATH=\(envPath)")
+        }
+    }
+
+    // 4. Env-var inline token.
+    if let envToken = envVar("DVAI_LICENSE_TOKEN") {
+        return (
+            envToken.trimmingCharacters(in: .whitespacesAndNewlines),
+            "DVAI_LICENSE_TOKEN env var"
+        )
+    }
+
+    // 5. Bundle resource (dvai-license.jwt next to the app's other
+    //    bundled resources).
+    if let bundleURL = Bundle.main.url(forResource: "dvai-license", withExtension: "jwt") {
+        if let loaded = tryLoadFromPath(bundleURL.path) {
+            return (loaded, "Bundle.main resource dvai-license.jwt")
+        }
+    }
+
+    // 6. Application Support / dvai-bridge / dvai-license.jwt.
+    if let appSupportURL = (try? FileManager.default.url(
+        for: .applicationSupportDirectory,
+        in: .userDomainMask,
+        appropriateFor: nil,
+        create: false
+    )) {
+        let candidate = appSupportURL
+            .appendingPathComponent("dvai-bridge", isDirectory: true)
+            .appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME)
+        if let loaded = tryLoadFromPath(candidate.path) {
+            return (loaded, candidate.path)
+        }
+    }
+
+    // 7. Documents directory.
+    if let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first {
+        let candidate = docsURL.appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME)
+        if let loaded = tryLoadFromPath(candidate.path) {
+            return (loaded, candidate.path)
+        }
+    }
+
+    // 8. (Optional) App Group container, if configured.
+    if let groupId = options.appGroupIdentifier, !groupId.isEmpty {
+        if let groupURL = FileManager.default
+            .containerURL(forSecurityApplicationGroupIdentifier: groupId)?
+            .appendingPathComponent(DVAI_DEFAULT_LICENSE_FILENAME) {
+            if let loaded = tryLoadFromPath(groupURL.path) {
+                return (loaded, groupURL.path)
+            }
+        }
+    }
+
+    return nil
+}
+
+/// Read a file at `path` and return its trimmed UTF-8 contents, or
+/// nil on any error (missing / permission / encoding).
+private func tryLoadFromPath(_ path: String) -> String? {
+    let fm = FileManager.default
+    guard fm.fileExists(atPath: path) else { return nil }
+    guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else { return nil }
+    guard let text = String(data: data, encoding: .utf8) else { return nil }
+    let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+}