@dvai-bridge/ios 4.0.0 → 4.0.1

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

@@ -1,114 +1,114 @@
-/*
- * Public-key registry for DVAI-Bridge license JWT verification on iOS.
- *
- * Mirrors `packages/dvai-bridge-core/src/license/publicKeys.ts`.
- *
- * Each entry is keyed by `kid` (key id, written by the license generator
- * into the JWT header). The SDK looks up the matching entry by kid when
- * verifying a license token. Multiple entries can coexist so that key
- * rotation is non-disruptive: ship the new key in a release alongside
- * the old, leave the old in place for ~12 months while previously-
- * issued licenses naturally expire or get re-issued, then prune.
- *
- * THE PRIVATE KEY DOES NOT LIVE HERE. It belongs in your secrets
- * manager (1Password / AWS Secrets Manager / Vault), accessible only
- * to the license-generator service that produces signed JWTs. The
- * mathematics of ECDSA P-256 guarantee that a holder of the public
- * key alone cannot forge a signature.
- *
- * To populate this registry:
- *   1. Run `node scripts/license/generate-keypair.mjs` (see that
- *      script's comment for full instructions)
- *   2. Paste the printed PUBLIC key JWK as an entry below — and into
- *      the matching `publicKeys.ts` for the JS-side validator
- *   3. Move the printed PRIVATE key into your secrets store
- *   4. Wire your license-generator backend to use the private key
- */
-import Foundation
-
-/// ES256 (ECDSA P-256) public key in JWK form. The shape matches the
-/// IANA JWK spec — x/y are base64url-encoded 32-byte big-endian
-/// coordinates. Same fields as the JS-side `DvaiPublicKeyJwk`.
-public struct DvaiPublicKeyJwk: Sendable, Equatable {
-    /// Always `"EC"` for ECDSA keys.
-    public let kty: String
-    /// Always `"P-256"` for ES256.
-    public let crv: String
-    /// Base64url-encoded X coordinate (32 bytes).
-    public let x: String
-    /// Base64url-encoded Y coordinate (32 bytes).
-    public let y: String
-    /// Algorithm hint. Should be `"ES256"` for our keys.
-    public let alg: String?
-    /// Key use hint. Should be `"sig"`.
-    public let use: String?
-    /// Key identifier — must match the JWT header `kid` to be selected.
-    public let kid: String?
-
-    public init(
-        kty: String = "EC",
-        crv: String = "P-256",
-        x: String,
-        y: String,
-        alg: String? = "ES256",
-        use: String? = "sig",
-        kid: String? = nil
-    ) {
-        self.kty = kty
-        self.crv = crv
-        self.x = x
-        self.y = y
-        self.alg = alg
-        self.use = use
-        self.kid = kid
-    }
-}
-
-/// `kid` reserved for the placeholder key below. The validator refuses
-/// to accept tokens signed with this kid unless the caller explicitly
-/// opts in (`allowPlaceholderKey: true` passed to the validator
-/// constructor). Used by tests and by the sample license printed by
-/// `generate-keypair.mjs`.
-public let DVAI_PLACEHOLDER_KID = "placeholder-do-not-ship"
-
-/// Registry mapping `kid` → public key JWK.
-///
-/// WARNING: The entry below is a **placeholder** — it is a published,
-/// well-known test keypair and DOES NOT verify any real production
-/// license. Before shipping licenses to customers, replace it with the
-/// output of `scripts/license/generate-keypair.mjs`. The SDK refuses
-/// to validate licenses against the placeholder kid
-/// `"placeholder-do-not-ship"` unless `allowPlaceholderKey: true` is
-/// passed to the validator (test-only escape hatch).
-///
-/// Adding a new key for rotation:
-///
-///     public let DVAI_PUBLIC_KEYS: [String: DvaiPublicKeyJwk] = [
-///         "2026-05": DvaiPublicKeyJwk(x: "...", y: "...", kid: "2026-05"),
-///         "2027-01": DvaiPublicKeyJwk(x: "...", y: "...", kid: "2027-01"),
-///     ]
-public let DVAI_PUBLIC_KEYS: [String: DvaiPublicKeyJwk] = [
-    // Production key, kid `2026-05`. Generated 2026-05-15 by
-    // scripts/license/generate-keypair.mjs. The matching private key
-    // lives in the operator's secrets manager.
-    "2026-05": DvaiPublicKeyJwk(
-        x: "2Y8TuhnlE4tiVDtliozYTgc1TAqi4_TBTI6FHe1p_Vw",
-        y: "pyxMJHj10HPe2hnpJvMpnZ4AzpYZRfqGEMhpBr1-Oto",
-        alg: "ES256",
-        use: "sig",
-        kid: "2026-05"
-    ),
-    // PLACEHOLDER — used by the SDK's own unit tests and by the sample
-    // license printed by `generate-keypair.mjs`. The validator REFUSES
-    // to accept tokens signed under this kid unless `allowPlaceholderKey:
-    // true` is passed to the validator constructor (test-only escape
-    // hatch). Safe to keep in production builds; remove only if you
-    // want test fixtures to stop working.
-    DVAI_PLACEHOLDER_KID: DvaiPublicKeyJwk(
-        x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
-        y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
-        alg: "ES256",
-        use: "sig",
-        kid: DVAI_PLACEHOLDER_KID
-    ),
-]
+/*
+ * Public-key registry for DVAI-Bridge license JWT verification on iOS.
+ *
+ * Mirrors `packages/dvai-bridge-core/src/license/publicKeys.ts`.
+ *
+ * Each entry is keyed by `kid` (key id, written by the license generator
+ * into the JWT header). The SDK looks up the matching entry by kid when
+ * verifying a license token. Multiple entries can coexist so that key
+ * rotation is non-disruptive: ship the new key in a release alongside
+ * the old, leave the old in place for ~12 months while previously-
+ * issued licenses naturally expire or get re-issued, then prune.
+ *
+ * THE PRIVATE KEY DOES NOT LIVE HERE. It belongs in your secrets
+ * manager (1Password / AWS Secrets Manager / Vault), accessible only
+ * to the license-generator service that produces signed JWTs. The
+ * mathematics of ECDSA P-256 guarantee that a holder of the public
+ * key alone cannot forge a signature.
+ *
+ * To populate this registry:
+ *   1. Run `node scripts/license/generate-keypair.mjs` (see that
+ *      script's comment for full instructions)
+ *   2. Paste the printed PUBLIC key JWK as an entry below — and into
+ *      the matching `publicKeys.ts` for the JS-side validator
+ *   3. Move the printed PRIVATE key into your secrets store
+ *   4. Wire your license-generator backend to use the private key
+ */
+import Foundation
+
+/// ES256 (ECDSA P-256) public key in JWK form. The shape matches the
+/// IANA JWK spec — x/y are base64url-encoded 32-byte big-endian
+/// coordinates. Same fields as the JS-side `DvaiPublicKeyJwk`.
+public struct DvaiPublicKeyJwk: Sendable, Equatable {
+    /// Always `"EC"` for ECDSA keys.
+    public let kty: String
+    /// Always `"P-256"` for ES256.
+    public let crv: String
+    /// Base64url-encoded X coordinate (32 bytes).
+    public let x: String
+    /// Base64url-encoded Y coordinate (32 bytes).
+    public let y: String
+    /// Algorithm hint. Should be `"ES256"` for our keys.
+    public let alg: String?
+    /// Key use hint. Should be `"sig"`.
+    public let use: String?
+    /// Key identifier — must match the JWT header `kid` to be selected.
+    public let kid: String?
+
+    public init(
+        kty: String = "EC",
+        crv: String = "P-256",
+        x: String,
+        y: String,
+        alg: String? = "ES256",
+        use: String? = "sig",
+        kid: String? = nil
+    ) {
+        self.kty = kty
+        self.crv = crv
+        self.x = x
+        self.y = y
+        self.alg = alg
+        self.use = use
+        self.kid = kid
+    }
+}
+
+/// `kid` reserved for the placeholder key below. The validator refuses
+/// to accept tokens signed with this kid unless the caller explicitly
+/// opts in (`allowPlaceholderKey: true` passed to the validator
+/// constructor). Used by tests and by the sample license printed by
+/// `generate-keypair.mjs`.
+public let DVAI_PLACEHOLDER_KID = "placeholder-do-not-ship"
+
+/// Registry mapping `kid` → public key JWK.
+///
+/// WARNING: The entry below is a **placeholder** — it is a published,
+/// well-known test keypair and DOES NOT verify any real production
+/// license. Before shipping licenses to customers, replace it with the
+/// output of `scripts/license/generate-keypair.mjs`. The SDK refuses
+/// to validate licenses against the placeholder kid
+/// `"placeholder-do-not-ship"` unless `allowPlaceholderKey: true` is
+/// passed to the validator (test-only escape hatch).
+///
+/// Adding a new key for rotation:
+///
+///     public let DVAI_PUBLIC_KEYS: [String: DvaiPublicKeyJwk] = [
+///         "2026-05": DvaiPublicKeyJwk(x: "...", y: "...", kid: "2026-05"),
+///         "2027-01": DvaiPublicKeyJwk(x: "...", y: "...", kid: "2027-01"),
+///     ]
+public let DVAI_PUBLIC_KEYS: [String: DvaiPublicKeyJwk] = [
+    // Production key, kid `2026-05`. Generated 2026-05-15 by
+    // scripts/license/generate-keypair.mjs. The matching private key
+    // lives in the operator's secrets manager.
+    "2026-05": DvaiPublicKeyJwk(
+        x: "2Y8TuhnlE4tiVDtliozYTgc1TAqi4_TBTI6FHe1p_Vw",
+        y: "pyxMJHj10HPe2hnpJvMpnZ4AzpYZRfqGEMhpBr1-Oto",
+        alg: "ES256",
+        use: "sig",
+        kid: "2026-05"
+    ),
+    // PLACEHOLDER — used by the SDK's own unit tests and by the sample
+    // license printed by `generate-keypair.mjs`. The validator REFUSES
+    // to accept tokens signed under this kid unless `allowPlaceholderKey:
+    // true` is passed to the validator constructor (test-only escape
+    // hatch). Safe to keep in production builds; remove only if you
+    // want test fixtures to stop working.
+    DVAI_PLACEHOLDER_KID: DvaiPublicKeyJwk(
+        x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+        y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+        alg: "ES256",
+        use: "sig",
+        kid: DVAI_PLACEHOLDER_KID
+    ),
+]

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

@@ -1,195 +1,195 @@
-/*
- * Type surface for the DVAI-Bridge offline JWT license system on iOS.
- *
- * Mirrors `packages/dvai-bridge-core/src/license/types.ts`. The whole
- * license flow is deliberately small:
- *   1. A signed JWT (produced server-side by your license generator) is
- *      either dropped at a platform-default path (e.g. bundled as a
- *      `dvai-license.jwt` resource), pointed at via
- *      `LicenseValidatorOptions.path`, or pasted directly into
- *      `LicenseValidatorOptions.token`.
- *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
- *      key registry in `PublicKeys.swift`, and checks four runtime
- *      claims:
- *        - signature must verify against a known kid
- *        - `exp` must be in the future
- *        - `aud` must include the current audience (Bundle.main.bundleIdentifier)
- *        - `platforms` must include the current SDK platform (.ios)
- *   3. The outcome is summarised in a `LicenseStatus` value the rest of
- *      the SDK can dispatch on.
- *
- * Nothing in this file makes network calls. The entire flow is offline.
- *
- * The wire format (JWT header + payload + ES256 signature) is byte-for-
- * byte equivalent to the JS-side validator — the same .jwt file works
- * across iOS, Android, .NET, Flutter, RN, and JS SDKs.
- */
-import Foundation
-#if !COCOAPODS
-import JWTKit
-#endif
-
-/// Recognised license tiers. `commercial` and `trial` come from the
-/// signed token's `tier` claim; the `free*` variants are produced
-/// internally by the validator. Anything unknown collapses to
-/// `.freeProd` defensively.
-public enum LicenseTier: String, Sendable, Codable, Equatable {
-    case commercial
-    case trial
-    /// Running in DEBUG / simulator / DVAI_FORCE_DEV — no badge required.
-    case freeDev = "free-dev"
-    /// Production build with no valid license — badge required.
-    case freeProd = "free-prod"
-    /// Had a valid license but `exp` is past — badge required + warn.
-    case freeExpired = "free-expired"
-}
-
-/// Platform identifiers the SDK recognises in license `platforms` claims.
-/// Matches the JS-side enum exactly so a single .jwt activates across
-/// every SDK that lists its identifier.
-public enum DvaiPlatform: String, Sendable, Codable, Equatable {
-    case web
-    case node
-    case ios
-    case android
-    case dotnet
-    case flutter
-    case reactNative = "react-native"
-    case capacitor
-}
-
-/// Result of license validation. Use the `kind` case to dispatch — the
-/// associated values vary per case (matching the JS-side discriminated
-/// union exactly).
-public enum LicenseStatus: Sendable, Equatable {
-    /// Active commercial license. Audience + platform binding verified.
-    case commercial(licensee: String, expiresAt: Int64, platform: DvaiPlatform, audienceMatched: String)
-
-    /// Active trial license. Same shape as commercial — the SDK treats
-    /// both as "premium" (no attribution badge).
-    case trial(licensee: String, expiresAt: Int64, platform: DvaiPlatform, audienceMatched: String)
-
-    /// Running in a developer environment — license enforcement bypassed.
-    /// `reason` describes which heuristic matched (for logs/dashboard).
-    case freeDev(reason: String)
-
-    /// Production build with no valid license. `reason` is the human-
-    /// readable explanation: missing file, signature didn't verify,
-    /// audience mismatch, etc. The SDK throws on this status in
-    /// `validateAndAssert()`.
-    case freeProd(reason: String)
-
-    /// Had a valid license but `exp` is past. Surfaced separately so the
-    /// developer/dashboard knows whose renewal to chase. Throws in
-    /// `validateAndAssert()`.
-    case freeExpired(licensee: String, expiredAt: Int64)
-
-    /// True when the status represents a paid / unwatermarked tier.
-    public var isPaid: Bool {
-        switch self {
-        case .commercial, .trial: return true
-        case .freeDev, .freeProd, .freeExpired: return false
-        }
-    }
-
-    /// Stable string identifier per case — useful for logging and for
-    /// matching the JS-side `status.kind` field 1:1.
-    public var kind: String {
-        switch self {
-        case .commercial: return "commercial"
-        case .trial: return "trial"
-        case .freeDev: return "free-dev"
-        case .freeProd: return "free-prod"
-        case .freeExpired: return "free-expired"
-        }
-    }
-}
-
-/// JWT payload shape we issue. Conforms to `JWTPayload` so JWTKit can
-/// decode it; the `verify(using:)` method is a no-op because we run our
-/// own claim verification at the `LicenseValidator` level (so we can
-/// produce specific free-prod reasons rather than generic JWT errors).
-///
-/// The wire field names use `aud` / `iss` etc. directly so the JSON is
-/// identical to the JS-side payload.
-public struct DvaiLicensePayload: Codable, Equatable {
-    /// Standard JWT issuer. Must equal `"DVAI-Bridge"`.
-    public let iss: String
-    /// Standard subject — internal license id.
-    public let sub: String
-    /// Audience binding: exact strings OR `*.example.com` wildcard subdomain
-    /// patterns OR `*` (any-domain). Matched against
-    /// `Bundle.main.bundleIdentifier` at runtime.
-    public let aud: [String]
-    /// Tier the license grants. Only `commercial` / `trial` are valid
-    /// here — `free*` is computed by the validator, never claimed.
-    public let tier: String
-    /// Which SDK platforms this license activates. Current runtime must
-    /// be in this list for the license to apply.
-    public let platforms: [String]
-    /// Display name of the licensee, for audit logs and dashboards.
-    public let licensee: String
-    /// Standard JWT issued-at (seconds since Unix epoch).
-    public let iat: Int64
-    /// Standard JWT expiry (seconds since Unix epoch).
-    public let exp: Int64
-
-    public init(
-        iss: String,
-        sub: String,
-        aud: [String],
-        tier: String,
-        platforms: [String],
-        licensee: String,
-        iat: Int64,
-        exp: Int64
-    ) {
-        self.iss = iss
-        self.sub = sub
-        self.aud = aud
-        self.tier = tier
-        self.platforms = platforms
-        self.licensee = licensee
-        self.iat = iat
-        self.exp = exp
-    }
-}
-
-#if !COCOAPODS
-extension DvaiLicensePayload: JWTPayload {
-    /// JWTKit hook — we intentionally do NOT verify exp/aud here, because
-    /// the validator wants specific failure reasons per claim. JWTKit's
-    /// `verify(_:as:)` will still verify the signature; the claim
-    /// verification happens in `LicenseValidator.verifyToken`.
-    public func verify(using algorithm: some JWTAlgorithm) async throws {
-        // No-op: see comment above.
-    }
-}
-#endif
-
-/// Thrown by `LicenseValidator.validateAndAssert()` (and propagated from
-/// `DVAIBridge.start(...)`) when an SDK consumer attempts to run the
-/// library in a production / release context without a valid commercial
-/// or trial license.
-///
-/// The error message is intentionally verbose: it tells the developer
-/// exactly which check failed, how to resolve it, where to put the
-/// license file, and how to bypass for local development. This is the
-/// front line of the BSL 1.1 commercial enforcement story — surface it
-/// clearly enough that a developer can unblock themselves without a
-/// support ticket.
-///
-/// The `status` field carries the underlying `LicenseStatus` so
-/// programmatic callers can dispatch on `err.status.kind` if they
-/// want to handle expired vs. missing differently.
-public struct LicenseRequiredError: Error, LocalizedError, Sendable {
-    public let message: String
-    public let status: LicenseStatus
-
-    public init(message: String, status: LicenseStatus) {
-        self.message = message
-        self.status = status
-    }
-
-    public var errorDescription: String? { message }
-}
+/*
+ * Type surface for the DVAI-Bridge offline JWT license system on iOS.
+ *
+ * Mirrors `packages/dvai-bridge-core/src/license/types.ts`. The whole
+ * license flow is deliberately small:
+ *   1. A signed JWT (produced server-side by your license generator) is
+ *      either dropped at a platform-default path (e.g. bundled as a
+ *      `dvai-license.jwt` resource), pointed at via
+ *      `LicenseValidatorOptions.path`, or pasted directly into
+ *      `LicenseValidatorOptions.token`.
+ *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
+ *      key registry in `PublicKeys.swift`, and checks four runtime
+ *      claims:
+ *        - signature must verify against a known kid
+ *        - `exp` must be in the future
+ *        - `aud` must include the current audience (Bundle.main.bundleIdentifier)
+ *        - `platforms` must include the current SDK platform (.ios)
+ *   3. The outcome is summarised in a `LicenseStatus` value the rest of
+ *      the SDK can dispatch on.
+ *
+ * Nothing in this file makes network calls. The entire flow is offline.
+ *
+ * The wire format (JWT header + payload + ES256 signature) is byte-for-
+ * byte equivalent to the JS-side validator — the same .jwt file works
+ * across iOS, Android, .NET, Flutter, RN, and JS SDKs.
+ */
+import Foundation
+#if !COCOAPODS
+import JWTKit
+#endif
+
+/// Recognised license tiers. `commercial` and `trial` come from the
+/// signed token's `tier` claim; the `free*` variants are produced
+/// internally by the validator. Anything unknown collapses to
+/// `.freeProd` defensively.
+public enum LicenseTier: String, Sendable, Codable, Equatable {
+    case commercial
+    case trial
+    /// Running in DEBUG / simulator / DVAI_FORCE_DEV — no badge required.
+    case freeDev = "free-dev"
+    /// Production build with no valid license — badge required.
+    case freeProd = "free-prod"
+    /// Had a valid license but `exp` is past — badge required + warn.
+    case freeExpired = "free-expired"
+}
+
+/// Platform identifiers the SDK recognises in license `platforms` claims.
+/// Matches the JS-side enum exactly so a single .jwt activates across
+/// every SDK that lists its identifier.
+public enum DvaiPlatform: String, Sendable, Codable, Equatable {
+    case web
+    case node
+    case ios
+    case android
+    case dotnet
+    case flutter
+    case reactNative = "react-native"
+    case capacitor
+}
+
+/// Result of license validation. Use the `kind` case to dispatch — the
+/// associated values vary per case (matching the JS-side discriminated
+/// union exactly).
+public enum LicenseStatus: Sendable, Equatable {
+    /// Active commercial license. Audience + platform binding verified.
+    case commercial(licensee: String, expiresAt: Int64, platform: DvaiPlatform, audienceMatched: String)
+
+    /// Active trial license. Same shape as commercial — the SDK treats
+    /// both as "premium" (no attribution badge).
+    case trial(licensee: String, expiresAt: Int64, platform: DvaiPlatform, audienceMatched: String)
+
+    /// Running in a developer environment — license enforcement bypassed.
+    /// `reason` describes which heuristic matched (for logs/dashboard).
+    case freeDev(reason: String)
+
+    /// Production build with no valid license. `reason` is the human-
+    /// readable explanation: missing file, signature didn't verify,
+    /// audience mismatch, etc. The SDK throws on this status in
+    /// `validateAndAssert()`.
+    case freeProd(reason: String)
+
+    /// Had a valid license but `exp` is past. Surfaced separately so the
+    /// developer/dashboard knows whose renewal to chase. Throws in
+    /// `validateAndAssert()`.
+    case freeExpired(licensee: String, expiredAt: Int64)
+
+    /// True when the status represents a paid / unwatermarked tier.
+    public var isPaid: Bool {
+        switch self {
+        case .commercial, .trial: return true
+        case .freeDev, .freeProd, .freeExpired: return false
+        }
+    }
+
+    /// Stable string identifier per case — useful for logging and for
+    /// matching the JS-side `status.kind` field 1:1.
+    public var kind: String {
+        switch self {
+        case .commercial: return "commercial"
+        case .trial: return "trial"
+        case .freeDev: return "free-dev"
+        case .freeProd: return "free-prod"
+        case .freeExpired: return "free-expired"
+        }
+    }
+}
+
+/// JWT payload shape we issue. Conforms to `JWTPayload` so JWTKit can
+/// decode it; the `verify(using:)` method is a no-op because we run our
+/// own claim verification at the `LicenseValidator` level (so we can
+/// produce specific free-prod reasons rather than generic JWT errors).
+///
+/// The wire field names use `aud` / `iss` etc. directly so the JSON is
+/// identical to the JS-side payload.
+public struct DvaiLicensePayload: Codable, Equatable {
+    /// Standard JWT issuer. Must equal `"DVAI-Bridge"`.
+    public let iss: String
+    /// Standard subject — internal license id.
+    public let sub: String
+    /// Audience binding: exact strings OR `*.example.com` wildcard subdomain
+    /// patterns OR `*` (any-domain). Matched against
+    /// `Bundle.main.bundleIdentifier` at runtime.
+    public let aud: [String]
+    /// Tier the license grants. Only `commercial` / `trial` are valid
+    /// here — `free*` is computed by the validator, never claimed.
+    public let tier: String
+    /// Which SDK platforms this license activates. Current runtime must
+    /// be in this list for the license to apply.
+    public let platforms: [String]
+    /// Display name of the licensee, for audit logs and dashboards.
+    public let licensee: String
+    /// Standard JWT issued-at (seconds since Unix epoch).
+    public let iat: Int64
+    /// Standard JWT expiry (seconds since Unix epoch).
+    public let exp: Int64
+
+    public init(
+        iss: String,
+        sub: String,
+        aud: [String],
+        tier: String,
+        platforms: [String],
+        licensee: String,
+        iat: Int64,
+        exp: Int64
+    ) {
+        self.iss = iss
+        self.sub = sub
+        self.aud = aud
+        self.tier = tier
+        self.platforms = platforms
+        self.licensee = licensee
+        self.iat = iat
+        self.exp = exp
+    }
+}
+
+#if !COCOAPODS
+extension DvaiLicensePayload: JWTPayload {
+    /// JWTKit hook — we intentionally do NOT verify exp/aud here, because
+    /// the validator wants specific failure reasons per claim. JWTKit's
+    /// `verify(_:as:)` will still verify the signature; the claim
+    /// verification happens in `LicenseValidator.verifyToken`.
+    public func verify(using algorithm: some JWTAlgorithm) async throws {
+        // No-op: see comment above.
+    }
+}
+#endif
+
+/// Thrown by `LicenseValidator.validateAndAssert()` (and propagated from
+/// `DVAIBridge.start(...)`) when an SDK consumer attempts to run the
+/// library in a production / release context without a valid commercial
+/// or trial license.
+///
+/// The error message is intentionally verbose: it tells the developer
+/// exactly which check failed, how to resolve it, where to put the
+/// license file, and how to bypass for local development. This is the
+/// front line of the BSL 1.1 commercial enforcement story — surface it
+/// clearly enough that a developer can unblock themselves without a
+/// support ticket.
+///
+/// The `status` field carries the underlying `LicenseStatus` so
+/// programmatic callers can dispatch on `err.status.kind` if they
+/// want to handle expired vs. missing differently.
+public struct LicenseRequiredError: Error, LocalizedError, Sendable {
+    public let message: String
+    public let status: LicenseStatus
+
+    public init(message: String, status: LicenseStatus) {
+        self.message = message
+        self.status = status
+    }
+
+    public var errorDescription: String? { message }
+}