@unisim/sdk 0.122.2 → 0.123.0

package/dist/sessionStorage.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The shape supabase-js wants for `auth.storage`. Every method may be async —
+ * the Keychain bridge is, and supabase-js awaits all three.
+ */
+export interface SessionStorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * The synchronous subset — what the cookie adapter actually is.
+ *
+ * ⚠️ Keep this distinction. The active-org and language stores read their
+ * value inside a `useState` INITIALISER, which cannot await; typing the cookie
+ * adapter as merely "possibly async" made those reads compile as
+ * `Promise<string> | string | null` and the org id would have been a pending
+ * promise stringified into a cookie. The compiler caught it; the runtime would
+ * not have said anything.
+ */
+export interface SyncSessionStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * True inside a Capacitor container (iOS/Android), false in any browser.
+ *
+ * ⚠️ Deliberately does NOT trust `cookieDomain` or the build mode to tell it
+ * apart. Every product computes `cookieDomain` from `import.meta.env.PROD`,
+ * which is true in the native bundle as well as the web one — that shared
+ * expression is exactly what made the native session storage silently wrong.
+ */
+export declare function isNativeShell(): boolean;
+interface SuiteAuthPlugin {
+    get(options: {
+        key: string;
+    }): Promise<{
+        value: string | null;
+    }>;
+    set(options: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    remove(options: {
+        key: string;
+    }): Promise<void>;
+}
+/** True when this native build can reach the shared-Keychain plugin. */
+export declare function hasSharedKeychain(): boolean;
+/**
+ * Keychain-backed storage, shared across every suite app signed by the same
+ * team. Async, which supabase-js supports.
+ *
+ * ⚠️ On a plugin ERROR this falls back to localStorage for that call, so a
+ * Keychain hiccup degrades to an app-local session rather than signing the
+ * user out. A plugin returning `null` is NOT an error — it means "no session
+ * in the shared store", and must be reported as such, or a sign-out in one app
+ * would never be seen by the others.
+ */
+export declare function createSharedKeychainStorage(plugin: SuiteAuthPlugin): SessionStorageAdapter;
+/**
+ * Cookie-backed storage — the load-bearing piece for cross-subdomain SSO.
+ * supabase-js defaults to localStorage which is origin-scoped, so a session
+ * created at app.unisim.co.uk wouldn't be visible to a product at
+ * assess.unisim.co.uk. Writing the session JSON into a cookie scoped to the
+ * parent zone (.unisim.co.uk) means every subdomain reads the same auth.
+ *
+ * ⚠️ Only usable from an origin that actually sits under `domain`. From
+ * anywhere else — `capacitor://localhost`, a dev server on localhost, a
+ * file:// Electron renderer — the browser rejects the write outright and every
+ * read returns null. `chooseSessionStorage()` is what keeps that from
+ * happening; don't reach for this adapter directly.
+ */
+export declare function createCookieStorage(domain: string): SyncSessionStorageAdapter;
+export type SessionStorageKind = 'shared-keychain' | 'native-local' | 'shared-cookie' | 'local';
+export interface ChosenSessionStorage {
+    kind: SessionStorageKind;
+    /** `undefined` means "let supabase-js use its own localStorage adapter". */
+    storage: SessionStorageAdapter | undefined;
+    /** Whether sibling suite state (active org) may ride the same cookie. */
+    cookiesUsable: boolean;
+}
+/**
+ * Pick the session store for the platform this code is running on.
+ *
+ * The native check comes FIRST and overrides `cookieDomain`, because every
+ * native build sets `cookieDomain` and none of them can use it.
+ */
+export declare function chooseSessionStorage(cookieDomain?: string): ChosenSessionStorage;
+export {};
+//# sourceMappingURL=sessionStorage.d.ts.map

package/dist/sessionStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStorage.d.ts","sourceRoot":"","sources":["../src/sessionStorage.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC5D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAgBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAcvC;AAID,UAAU,eAAe;IACvB,GAAG,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAChE,GAAG,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,MAAM,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChD;AAOD,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAQD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,qBAAqB,CAmD1F;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB,CA0C7E;AAID,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,cAAc,GACd,eAAe,GACf,OAAO,CAAA;AAEX,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAA;IACxB,4EAA4E;IAC5E,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAAA;IAC1C,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAsBhF"}

package/dist/sessionStorage.js

@@ -0,0 +1,239 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Where the Supabase session lives, per platform.
+//
+// supabase-js keeps the session in whatever `auth.storage` it is handed. The
+// suite needs three different answers, and getting the wrong one is silent
+// every time — a session that fails to persist looks exactly like a session
+// that was never created:
+//
+//   • **Browser, production** — a cookie scoped to the parent zone
+//     (.unisim.co.uk), so app.unisim.co.uk and assess.unisim.co.uk read the
+//     same auth. This is the cross-subdomain SSO mechanism and predates this
+//     module; it moved here unchanged.
+//
+//   • **Browser, local dev / Electron** — localStorage. There is no parent
+//     zone to scope a cookie to on localhost or file://.
+//
+//   • **Native (Capacitor)** — the iOS Keychain, in a group shared by every
+//     suite app, via the UnisimSuiteAuth plugin. Falls back to localStorage
+//     when the plugin is absent.
+//
+// ⚠️ **The native case is why this module exists.** A Capacitor app runs at
+// `capacitor://localhost`, and a cookie written from there with
+// `Domain=.unisim.co.uk` is REJECTED by the cookie domain-match rule — the
+// write silently does nothing and the read comes back null. Every native build
+// sets `cookieDomain` (it is gated on `import.meta.env.PROD`, which is true in
+// the native bundle), so until this module landed **the native apps could not
+// persist a session at all**: sign in, force-quit, and you were signed out
+// again, with nothing logged. `sessionStorage.browser.test.mjs` pins that
+// behaviour so it cannot come back.
+//
+// The shared Keychain then buys the thing that was actually asked for: sign in
+// on Universal Images on the phone and Universal PDF is already signed in.
+// Sign-out is suite-wide too, which matches how the shared cookie already
+// behaves on the web.
+// ─────────────────────────────────────────────────────────────────────────────
+function capacitorGlobal() {
+    if (typeof window === 'undefined')
+        return null;
+    const c = window.Capacitor;
+    return c ?? null;
+}
+/**
+ * True inside a Capacitor container (iOS/Android), false in any browser.
+ *
+ * ⚠️ Deliberately does NOT trust `cookieDomain` or the build mode to tell it
+ * apart. Every product computes `cookieDomain` from `import.meta.env.PROD`,
+ * which is true in the native bundle as well as the web one — that shared
+ * expression is exactly what made the native session storage silently wrong.
+ */
+export function isNativeShell() {
+    const c = capacitorGlobal();
+    if (c && typeof c.isNativePlatform === 'function') {
+        try {
+            return c.isNativePlatform();
+        }
+        catch {
+            /* fall through to the protocol check */
+        }
+    }
+    // A partially-initialised bridge still serves the app from the container's
+    // own scheme, which no browser uses.
+    if (typeof window === 'undefined')
+        return false;
+    const protocol = window.location?.protocol;
+    return protocol === 'capacitor:' || protocol === 'ionic:';
+}
+function suiteAuthPlugin() {
+    const plugin = capacitorGlobal()?.Plugins?.UnisimSuiteAuth;
+    return plugin ? plugin : null;
+}
+/** True when this native build can reach the shared-Keychain plugin. */
+export function hasSharedKeychain() {
+    return suiteAuthPlugin() !== null;
+}
+function localStorageAdapter() {
+    // `undefined` lets supabase-js install its own localStorage adapter, which
+    // already handles the private-mode / storage-disabled throw.
+    return undefined;
+}
+/**
+ * Keychain-backed storage, shared across every suite app signed by the same
+ * team. Async, which supabase-js supports.
+ *
+ * ⚠️ On a plugin ERROR this falls back to localStorage for that call, so a
+ * Keychain hiccup degrades to an app-local session rather than signing the
+ * user out. A plugin returning `null` is NOT an error — it means "no session
+ * in the shared store", and must be reported as such, or a sign-out in one app
+ * would never be seen by the others.
+ */
+export function createSharedKeychainStorage(plugin) {
+    let warned = false;
+    const warn = (op, err) => {
+        if (warned)
+            return;
+        warned = true;
+        console.warn(`[unisim/sdk] shared Keychain ${op} failed; falling back to app-local storage. ` +
+            'Sign-in will not carry across the suite apps on this device.', err);
+    };
+    const local = {
+        get: (key) => {
+            try {
+                return window.localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        set: (key, value) => {
+            try {
+                window.localStorage.setItem(key, value);
+            }
+            catch { /* private mode */ }
+        },
+        remove: (key) => {
+            try {
+                window.localStorage.removeItem(key);
+            }
+            catch { /* private mode */ }
+        },
+    };
+    return {
+        async getItem(key) {
+            try {
+                const { value } = await plugin.get({ key });
+                return value ?? null;
+            }
+            catch (err) {
+                warn('read', err);
+                return local.get(key);
+            }
+        },
+        async setItem(key, value) {
+            try {
+                await plugin.set({ key, value });
+            }
+            catch (err) {
+                warn('write', err);
+                local.set(key, value);
+            }
+        },
+        async removeItem(key) {
+            try {
+                await plugin.remove({ key });
+            }
+            catch (err) {
+                warn('delete', err);
+                local.remove(key);
+            }
+        },
+    };
+}
+// ── Browser: the cross-subdomain cookie ──────────────────────────────────────
+/**
+ * Cookie-backed storage — the load-bearing piece for cross-subdomain SSO.
+ * supabase-js defaults to localStorage which is origin-scoped, so a session
+ * created at app.unisim.co.uk wouldn't be visible to a product at
+ * assess.unisim.co.uk. Writing the session JSON into a cookie scoped to the
+ * parent zone (.unisim.co.uk) means every subdomain reads the same auth.
+ *
+ * ⚠️ Only usable from an origin that actually sits under `domain`. From
+ * anywhere else — `capacitor://localhost`, a dev server on localhost, a
+ * file:// Electron renderer — the browser rejects the write outright and every
+ * read returns null. `chooseSessionStorage()` is what keeps that from
+ * happening; don't reach for this adapter directly.
+ */
+export function createCookieStorage(domain) {
+    const secure = typeof window !== 'undefined' && window.location.protocol === 'https:';
+    return {
+        getItem(key) {
+            if (typeof document === 'undefined')
+                return null;
+            const encoded = encodeURIComponent(key);
+            for (const cookie of document.cookie.split('; ')) {
+                const eq = cookie.indexOf('=');
+                const name = eq === -1 ? cookie : cookie.slice(0, eq);
+                if (name === encoded) {
+                    return eq === -1 ? '' : decodeURIComponent(cookie.slice(eq + 1));
+                }
+            }
+            return null;
+        },
+        setItem(key, value) {
+            if (typeof document === 'undefined')
+                return;
+            const parts = [
+                `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
+                'Path=/',
+                `Domain=${domain}`,
+                `Max-Age=${60 * 60 * 24 * 365}`, // 1 year
+                'SameSite=Lax',
+            ];
+            if (secure)
+                parts.push('Secure');
+            document.cookie = parts.join('; ');
+        },
+        removeItem(key) {
+            if (typeof document === 'undefined')
+                return;
+            const parts = [
+                `${encodeURIComponent(key)}=`,
+                'Path=/',
+                `Domain=${domain}`,
+                'Max-Age=0',
+                'SameSite=Lax',
+            ];
+            if (secure)
+                parts.push('Secure');
+            document.cookie = parts.join('; ');
+        },
+    };
+}
+/**
+ * Pick the session store for the platform this code is running on.
+ *
+ * The native check comes FIRST and overrides `cookieDomain`, because every
+ * native build sets `cookieDomain` and none of them can use it.
+ */
+export function chooseSessionStorage(cookieDomain) {
+    if (isNativeShell()) {
+        const plugin = suiteAuthPlugin();
+        if (plugin) {
+            return {
+                kind: 'shared-keychain',
+                storage: createSharedKeychainStorage(plugin),
+                cookiesUsable: false,
+            };
+        }
+        return { kind: 'native-local', storage: localStorageAdapter(), cookiesUsable: false };
+    }
+    if (cookieDomain) {
+        return {
+            kind: 'shared-cookie',
+            storage: createCookieStorage(cookieDomain),
+            cookiesUsable: true,
+        };
+    }
+    return { kind: 'local', storage: localStorageAdapter(), cookiesUsable: false };
+}
+//# sourceMappingURL=sessionStorage.js.map

package/dist/sessionStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStorage.js","sourceRoot":"","sources":["../src/sessionStorage.ts"],"names":[],"mappings":"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"}

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.2",
-  "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"