@unisim/sdk 0.122.3 → 0.123.0

package/ios/Sources/UnisimSuiteAuthPlugin/UnisimSuiteAuthPlugin.swift

@@ -0,0 +1,241 @@
+import Foundation
+import Capacitor
+import Security
+
+/// Stores the Universal Suite session in the iOS Keychain, in a group shared by
+/// every suite app signed by the same team — so signing in on Universal Images
+/// leaves you signed in when you open Universal PDF.
+///
+/// It exists because a Capacitor app runs at `capacitor://localhost`, where the
+/// suite's cross-subdomain auth cookie cannot be written at all: the browser
+/// rejects `Domain=.unisim.co.uk` from an origin outside that zone. Before this
+/// plugin the native builds could not persist a session even to THEMSELVES —
+/// sign in, force-quit, signed out again, nothing logged. See
+/// `src/sessionStorage.ts` and its browser test.
+///
+/// ⚠️ **Sharing needs an entitlement the plugin cannot add for you.** The host
+/// app must carry an `.entitlements` file declaring the shared group:
+///
+///     <key>keychain-access-groups</key>
+///     <array><string>$(AppIdentifierPrefix)co.uk.unisim.suite</string></array>
+///
+/// and reference it from `CODE_SIGN_ENTITLEMENTS` in the Xcode project. No
+/// `capacitor.config.json` change is needed — the team prefix is resolved at
+/// runtime. An app with NO entitlements file cannot use the Keychain at all:
+/// every call comes back `errSecMissingEntitlement` (-34018), which is also
+/// what an unsigned simulator build gets.
+///
+/// Without a resolvable group the plugin still stores the session, app-locally:
+/// it persists across launches but does NOT carry to the other suite apps.
+/// `status()` reports which of the two you actually got, because nothing about
+/// the behaviour makes that visible from the outside.
+@objc(UnisimSuiteAuthPlugin)
+public class UnisimSuiteAuthPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "UnisimSuiteAuthPlugin"
+    public let jsName = "UnisimSuiteAuth"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "get", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "set", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "remove", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "status", returnType: CAPPluginReturnPromise)
+    ]
+
+    /// One service for the whole suite. The `key` the JS side passes (Supabase's
+    /// `storageKey`, i.e. `universal-suite-auth`) becomes the account, so other
+    /// suite keys can share the same group later without colliding.
+    private static let service = "co.uk.unisim.suite.auth"
+
+    /// The group every suite app shares. Prefixed with the team's app-identifier
+    /// prefix at runtime — see `appIdentifierPrefix()`.
+    private static let defaultGroupSuffix = "co.uk.unisim.suite"
+
+    private static var cachedPrefix: String??
+
+    /// The team prefix iOS stamps on this app's keychain items, e.g. the
+    /// `ABCDE12345` in `ABCDE12345.co.uk.unisim.pdf`.
+    ///
+    /// ⚠️ Resolved at RUNTIME rather than hardcoded, and that is deliberate: the
+    /// entitlement is written as `$(AppIdentifierPrefix)co.uk.unisim.suite`, and
+    /// `kSecAttrAccessGroup` will only accept the expanded form. Baking a team
+    /// ID into the config of thirteen apps means thirteen places to be wrong,
+    /// and a wrong one fails as `errSecMissingEntitlement` at sign-in — far from
+    /// where the mistake was made.
+    ///
+    /// The trick is the documented one: write an item with NO access group, and
+    /// read back the group iOS assigned it, which is always
+    /// `<prefix>.<bundle id>`.
+    private static func appIdentifierPrefix() -> String? {
+        if let cached = cachedPrefix { return cached }
+
+        let base: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: "unisim.suite.prefix-probe"
+        ]
+
+        var query = base
+        query[kSecReturnAttributes as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+        var item: CFTypeRef?
+        var status = SecItemCopyMatching(query as CFDictionary, &item)
+        if status == errSecItemNotFound {
+            var insert = base
+            insert[kSecValueData as String] = Data()
+            insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+            insert[kSecReturnAttributes as String] = true
+            status = SecItemAdd(insert as CFDictionary, &item)
+        }
+
+        guard status == errSecSuccess,
+              let attributes = item as? [String: Any],
+              let group = attributes[kSecAttrAccessGroup as String] as? String,
+              let dot = group.firstIndex(of: ".") else {
+            cachedPrefix = .some(nil)
+            return nil
+        }
+
+        let prefix = String(group[group.startIndex..<dot])
+        cachedPrefix = .some(prefix)
+        return prefix
+    }
+
+    /// The group to store under, or nil to fall back to an app-local item.
+    private var accessGroup: String? {
+        // An explicit group wins — an escape hatch for an app that needs to sit
+        // outside the suite group, and the only way to override the runtime
+        // resolution if it ever gets this wrong.
+        if let explicit = getConfig().getString("accessGroup"), !explicit.isEmpty {
+            return explicit
+        }
+        let suffix = getConfig().getString("accessGroupSuffix") ?? Self.defaultGroupSuffix
+        guard let prefix = Self.appIdentifierPrefix() else { return nil }
+        return "\(prefix).\(suffix)"
+    }
+
+    private func baseQuery(for key: String) -> [String: Any] {
+        var query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: Self.service,
+            kSecAttrAccount as String: key
+        ]
+        if let group = accessGroup {
+            query[kSecAttrAccessGroup as String] = group
+        }
+        return query
+    }
+
+    /// ⚠️ Put the OSStatus in the MESSAGE, not just the code. Every one of these
+    /// failures is indistinguishable from the JS side otherwise — "Keychain
+    /// update failed" was all that came back from the first simulator run, and
+    /// the number was the only thing that would have identified it.
+    ///
+    /// The one worth recognising is **-34018 `errSecMissingEntitlement`**, which
+    /// means the process has no keychain entitlement to work with at all. Two
+    /// ways to get there: an app built with code signing disabled (an unsigned
+    /// simulator build has no `application-identifier`, so the Keychain refuses
+    /// everything), or a configured `accessGroup` that is not listed in the
+    /// app's `keychain-access-groups` — including one missing the team prefix.
+    private static func describe(_ operation: String, _ status: OSStatus) -> String {
+        let detail = SecCopyErrorMessageString(status, nil) as String? ?? "unknown error"
+        let hint = status == errSecMissingEntitlement
+            ? " — the app has no usable keychain entitlement (unsigned build, or accessGroup not in keychain-access-groups)"
+            : ""
+        return "Keychain \(operation) failed: OSStatus \(status) (\(detail))\(hint)"
+    }
+
+    @objc func status(_ call: CAPPluginCall) {
+        let group = accessGroup
+        call.resolve([
+            "shared": group != nil,
+            "accessGroup": group ?? NSNull(),
+            "appIdentifierPrefix": Self.appIdentifierPrefix() ?? NSNull()
+        ])
+    }
+
+    @objc func get(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("key is required")
+            return
+        }
+
+        var query = baseQuery(for: key)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+        switch status {
+        case errSecSuccess:
+            guard let data = item as? Data, let value = String(data: data, encoding: .utf8) else {
+                // Present but unreadable — treat as absent rather than throwing,
+                // so a corrupt item shows as "signed out" and can be overwritten
+                // by the next sign-in instead of wedging the app.
+                call.resolve(["value": NSNull()])
+                return
+            }
+            call.resolve(["value": value])
+        case errSecItemNotFound:
+            // ⚠️ NOT an error, and the JS side must not treat it as one. "No
+            // session in the shared store" is exactly what another suite app
+            // signing out looks like.
+            call.resolve(["value": NSNull()])
+        default:
+            call.reject(Self.describe("read", status), String(status))
+        }
+    }
+
+    @objc func set(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("key is required")
+            return
+        }
+        guard let value = call.getString("value"), let data = value.data(using: .utf8) else {
+            call.reject("value is required")
+            return
+        }
+
+        let query = baseQuery(for: key)
+        let attributes: [String: Any] = [
+            kSecValueData as String: data,
+            // Readable once the device has been unlocked after a reboot, and
+            // never synced to iCloud — a bearer token has no business on
+            // another device.
+            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock
+        ]
+
+        let updateStatus = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+        if updateStatus == errSecSuccess {
+            call.resolve()
+            return
+        }
+        if updateStatus != errSecItemNotFound {
+            call.reject(Self.describe("update", updateStatus), String(updateStatus))
+            return
+        }
+
+        var insert = query
+        insert.merge(attributes) { current, _ in current }
+        let addStatus = SecItemAdd(insert as CFDictionary, nil)
+        if addStatus == errSecSuccess {
+            call.resolve()
+        } else {
+            call.reject(Self.describe("write", addStatus), String(addStatus))
+        }
+    }
+
+    @objc func remove(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("key is required")
+            return
+        }
+
+        let status = SecItemDelete(baseQuery(for: key) as CFDictionary)
+        if status == errSecSuccess || status == errSecItemNotFound {
+            call.resolve()
+        } else {
+            call.reject(Self.describe("delete", status), String(status))
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unisim/sdk",
-  "version": "0.122.3",
-  "description": "Shared React SDK for the Universal Suite — auth, entitlements, usage telemetry, changelog, org admin.",
+  "version": "0.123.0",
+  "description": "Shared React SDK for the Universal Suite \u2014 auth, entitlements, usage telemetry, changelog, org admin.",
   "license": "MIT",
   "author": "Universal Simulation Ltd",
   "keywords": [
@@ -28,6 +28,11 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -40,12 +45,16 @@
   "files": [
     "dist",
     "electron",
+    "ios/Sources",
+    "Package.swift",
+    "UnisimSdk.podspec",
     "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
+    "test:session-storage": "npm run build && node tests/session-storage.browser.mjs",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
@@ -62,6 +71,7 @@
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.7",
     "pdf-lib": "^1.17.1",
+    "playwright": "^1.62.1",
     "react": "^18.3.0",
     "react-dom": "^18.3.1",
     "typescript": "^5.7.2"