Unlock Hub vaults in write mode via the Hub-iOS-License JWT

[tobihagemann]

Hub now returns a Hub-iOS-License header on the vault access-token response: a JWT signed by the License Server (ES512). It replaces Hub-Subscription-State for deciding whether a vault covered by a paid Hub license unlocks in write mode for a freemium user. The old header can't go away yet (older Hub versions are still in production), so it keeps working but is deprecated, and the new header takes precedence when present.

This adds JWS verification, which the codebase didn't do before (only JWE). A stateless HubLicenseVerifier checks the ES512/P-521 signature against the License Server's embedded public key and enforces exp manually (60s leeway). It's wired into HubAuthenticationViewModel.receivedExistingKey behind a @Dependency seam so tests can inject a test key. Precedence: when Hub-iOS-License is present the legacy header is ignored entirely; a bad signature surfaces an error and blocks the unlock rather than silently falling back. The result feeds the existing HubSubscriptionState persistence unchanged, so there's no DB migration and PermissionProvider is untouched.

The timeless .active/.inactive snapshot model is kept on purpose: exp gates once at unlock, matching how Hub-Subscription-State already behaves.

Flow

flowchart TD
  A[access-token response] --> B{Hub-iOS-License present?}
  B -- no --> C[Legacy Hub-Subscription-State path]
  B -- yes --> D[Verify ES512 signature]
  D -- bad signature or malformed --> E[Surface error and block unlock]
  D -- valid --> F{Not expired?}
  F -- yes --> G[Write mode .active]
  F -- no --> H[Read-only .inactive]

Loading

[coderabbitai]

Walkthrough

This PR introduces iOS license token verification for Hub authentication. It adds a new HubLicenseVerifier service that validates ES512-signed JWT tokens using an embedded P-521 public key, checking expiration dates with 60-second leeway. The view model is updated to check for hub-ios-license headers and derive subscription state from valid/expired license tokens, with fallback to the legacy hub-subscription-state header when no license is present. A comprehensive test suite validates token signature verification, expiration handling, and view model integration. An error message string is added for invalid license signatures.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• cryptomator/ios#404: Modifies the same continueToAccessCheck control flow in HubAuthenticationViewModel for state branching logic.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: enabling Hub vault unlocking in write mode via a new JWT-based license mechanism.
Description check	✅ Passed	The description comprehensively explains the feature, implementation approach, and precedence logic, directly relating to all changeset modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/hub-ios-license-jwt-unlock

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@CryptomatorCommon/Sources/CryptomatorCommonCore/Hub/HubLicenseVerifier.swift`:
- Around line 150-156: The mock's verify(token:) exits early when
verifyTokenThrowableError is set, so increment verifyTokenCallsCount and set
verifyTokenReceivedToken before throwing; update the method in
HubLicenseVerifier.verify(token:) to first increment verifyTokenCallsCount and
assign verifyTokenReceivedToken = token, then if verifyTokenThrowableError is
non-nil throw it, otherwise proceed to call verifyTokenClosure or return
verifyTokenReturnValue (keeping references to verifyTokenClosure and
verifyTokenReturnValue as currently used).

In
`@CryptomatorCommon/Tests/CryptomatorCommonCoreTests/Hub/HubAuthenticationViewModelTests.swift`:
- Around line 234-240: The test is setting hubLicenseVerifier only inside
withDependencies but HubAuthenticationViewModel (which captures
`@Dependency`(\.hubLicenseVerifier) at init) is created earlier in setUpWithError,
so resolveSubscriptionState(from:) may call the default verifier; fix by
instantiating a new HubAuthenticationViewModel inside the same withDependencies
block (or provide a factory helper that constructs HubAuthenticationViewModel
using current dependencies) immediately after overriding $0.hubLicenseVerifier
and before calling continueToAccessCheck(); apply the same pattern for the other
occurrences mentioned (lines around 266-272, 298-304, 329-335).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d0097921-37ef-4d43-911b-147594a4ee17

📥 Commits

Reviewing files that changed from the base of the PR and between 82492e4 and 94da6ec.

📒 Files selected for processing (5)

• CryptomatorCommon/Sources/CryptomatorCommonCore/Hub/HubAuthenticationViewModel.swift
• CryptomatorCommon/Sources/CryptomatorCommonCore/Hub/HubLicenseVerifier.swift
• CryptomatorCommon/Tests/CryptomatorCommonCoreTests/Hub/HubAuthenticationViewModelTests.swift
• CryptomatorCommon/Tests/CryptomatorCommonCoreTests/Hub/HubLicenseVerifierTests.swift
• SharedResources/en.lproj/Localizable.strings