@octane-xplat/secure-storage 0.9.0 → 0.10.0

package/README.md

@@ -1,24 +1,22 @@
 # `@octane-xplat/secure-storage`
 
-Keychain/Keystore-backed secret storage for Octane xplat apps. iOS writes
-to the Keychain and Android to the Keystore via
-`@nativescript/secure-storage`; Linux goes through the desktop host bridge
-to the Secret Service API (`org.freedesktop.secrets`); web and the macOS
-AppKit dev host report `supported: false` — IndexedDB and NSUserDefaults
-are not a trust boundary, so the leaf refuses to pretend.
-
 ```sh
 pnpm add @octane-xplat/secure-storage
 ```
 
+Store session tokens without displaying their contents. iOS and macOS use
+Keychain, Android uses the Keystore-backed plugin, and Linux uses the desktop
+host's Secret Service adapter. Plain browsers report `supported: false`.
+
 ```ts
 import { secureStorage } from '@octane-xplat/secure-storage'
 
-if (secureStorage.supported) {
-	const store = secureStorage.impl!
-	await store.set('session-token', token)
-	const token = await store.get('session-token')
-	await store.remove('session-token')
+// Call with a token issued by your app's backend; never log its value.
+async function saveSession(token: string) {
+	if ((await secureStorage.ensure()) !== 'granted' || !secureStorage.impl) return null
+	const store = secureStorage.impl
+	if (!(await store.set('session-token', token))) return null
+	return await store.get('session-token')
 }
 ```
 
@@ -27,8 +25,47 @@ implementation exists on this target — branch on it rather than catching —
 `ensure()` resolves the permission/availability state, and `impl` is an
 async string key-value store (`get` / `set` / `remove`).
 
+```ts
+if ((await secureStorage.ensure()) === 'granted') {
+	await secureStorage.impl!.remove('session-token')
+}
+```
+
 For non-secret preferences, use `storage` from
 [`@octane-xplat/platform`](../platform/README.md) instead.
 
-Guide: [Using device features](../../docs/platform-services.md);
-per-target availability: [platform notes](../../docs/platform-notes.md).
+Guide: [Using device features](../../docs/platform/platform-services.md);
+per-target availability: [platform notes](../../docs/notes/platform-notes.md).
+
+## macOS AppKit
+
+Install the leaf as an app runtime dependency. Use the CLI-owned
+`pnpm xplat dev --targets macos` or `pnpm xplat build --targets macos` workflow;
+it compiles the bundled Foundation/Security sources and loads their metadata
+before your JavaScript. See [native prerequisites](../../docs/platform/macos-native.md#prepare-the-app).
+No new UI dependency, host adapter, or runtime permission request is needed.
+A custom host without the native leaf reports unsupported.
+
+Keychain generic-password items use a service namespace owned by this leaf.
+Packaged apps are scoped by bundle identifier; keep that identifier stable
+across releases. CLI development hosts are scoped by the app's working directory.
+Moving that directory changes the development namespace, and development entries
+are separate from packaged entries. Items stay on this Mac and do not use iCloud
+synchronization. `remove()` deletes only the named item in that namespace.
+
+`ensure()` reports that the native implementation exists; it does not unlock the
+Keychain or guarantee the next operation succeeds. No authentication prompt is
+opened by the leaf. A missing key returns `null`; a failed read rejects with
+`Keychain read failed`, without keys, values, or native exception text. Writing the
+same key overwrites its value, and empty strings are preserved. Writes
+return `false` when Keychain access fails. Removal returns `true` for an already
+missing key and `false` for access failures. Handle these results in your sign-in
+flow rather than falling back to preferences or browser storage.
+
+From the repository root, `pnpm --filter @octane-xplat/secure-storage test:macos`
+checks the adapter and sanitized failures. `test:packed` checks package types;
+`test:macos-runtime` compiles a packed leaf and exercises real Keychain operations
+in an isolated host, including persistence across launches, bundle identity isolation,
+and a Vite build of its public import. That fixture creates
+random payloads in memory, prints only status markers, and removes its test items.
+It does not test UI input or locked-Keychain/signing policies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/secure-storage",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Keychain/Keystore-backed secure storage for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -22,12 +22,17 @@
     "directory": "packages/secure-storage"
   },
   "files": [
-    "src"
+    "src",
+    "types",
+    "platforms"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "macos": "./src/index.macos.ts",
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
       "default": "./src/index.ts"
     },
     "./*": "./src/*"
@@ -37,12 +42,13 @@
   },
   "dependencies": {
     "@nativescript/secure-storage": "4.0.2",
-    "@octane-xplat/platform": "0.9.0"
+    "@octane-xplat/platform": "0.10.0"
   },
   "devDependencies": {
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
-    "octane": "0.6.3"
+    "octane": "0.6.3",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
@@ -63,7 +69,17 @@
       "ios": "9.1.0"
     }
   },
+  "xplat": {
+    "macos": {
+      "frameworks": [
+        "Foundation",
+        "Security"
+      ]
+    }
+  },
   "scripts": {
-    "test:packed": "node tests/packed-consumer.mjs"
+    "test:packed": "node tests/macos.test.mjs && node tests/packed-consumer.mjs",
+    "test:macos": "node tests/macos.test.mjs",
+    "test:macos-runtime": "node tests/macos-runtime.mjs"
   }
 }

package/platforms/macos/include/XplatSecureStorage.h

@@ -0,0 +1,9 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+@interface XplatSecureStorage : NSObject
++ (NSDictionary *)get:(NSString *)key;
++ (BOOL)set:(NSDictionary *)options;
++ (BOOL)remove:(NSString *)key;
+@end
+NS_ASSUME_NONNULL_END

package/platforms/macos/src/XplatSecureStorage.m

@@ -0,0 +1,60 @@
+#import "XplatSecureStorage.h"
+#import <Security/Security.h>
+
+@implementation XplatSecureStorage
++ (NSMutableDictionary *)query:(NSString *)key {
+    // Packaged apps use their bundle ID. CLI development hosts share an
+    // executable, so scope those entries to the app's working directory.
+    NSString *identity = NSBundle.mainBundle.bundleIdentifier;
+    if (!identity.length) {
+        identity = [@"dev:" stringByAppendingString:NSFileManager.defaultManager.currentDirectoryPath];
+    }
+    return [@{
+        (__bridge id)kSecClass: (__bridge id)kSecClassGenericPassword,
+        (__bridge id)kSecAttrService: [@"org.octane.xplat.secure-storage:" stringByAppendingString:identity],
+        (__bridge id)kSecAttrAccount: key,
+        (__bridge id)kSecAttrSynchronizable: @NO,
+        (__bridge id)kSecUseAuthenticationUI: (__bridge id)kSecUseAuthenticationUIFail,
+    } mutableCopy];
+}
+
++ (NSDictionary *)get:(NSString *)key {
+    NSMutableDictionary *query = [self query:key];
+    query[(__bridge id)kSecReturnData] = @YES;
+    query[(__bridge id)kSecMatchLimit] = (__bridge id)kSecMatchLimitOne;
+    CFTypeRef item = NULL;
+    OSStatus status = SecItemCopyMatching((__bridge CFDictionaryRef)query, &item);
+    NSData *data = CFBridgingRelease(item);
+    NSString *value = status == errSecSuccess && [data isKindOfClass:NSData.class]
+        ? [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] : nil;
+    if (status == errSecSuccess && !value) status = errSecDecode;
+    return value ? @{ @"status": @(status), @"value": value } : @{ @"status": @(status) };
+}
+
++ (BOOL)set:(NSDictionary *)options {
+    NSString *key = options[@"key"];
+    NSString *value = options[@"value"];
+    if (![key isKindOfClass:NSString.class] || ![value isKindOfClass:NSString.class]) return NO;
+    NSData *data = [value dataUsingEncoding:NSUTF8StringEncoding];
+    if (!data) return NO;
+    NSMutableDictionary *query = [self query:key];
+    NSDictionary *update = @{ (__bridge id)kSecValueData: data };
+    OSStatus status = SecItemUpdate((__bridge CFDictionaryRef)query, (__bridge CFDictionaryRef)update);
+    if (status == errSecSuccess) return YES;
+    if (status != errSecItemNotFound) return NO;
+    query[(__bridge id)kSecValueData] = data;
+    query[(__bridge id)kSecAttrAccessible] = (__bridge id)kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly;
+    status = SecItemAdd((__bridge CFDictionaryRef)query, NULL);
+    // Another caller can insert between update and add. Never delete an
+    // existing item to overwrite it: preserve its access controls and value.
+    if (status == errSecDuplicateItem) {
+        return SecItemUpdate((__bridge CFDictionaryRef)[self query:key], (__bridge CFDictionaryRef)update) == errSecSuccess;
+    }
+    return status == errSecSuccess;
+}
+
++ (BOOL)remove:(NSString *)key {
+    OSStatus status = SecItemDelete((__bridge CFDictionaryRef)[self query:key]);
+    return status == errSecSuccess || status == errSecItemNotFound;
+}
+@end

package/src/secure-storage.macos.ts

@@ -1,9 +1,55 @@
-// Secure storage — AppKit host leaf. The dev host exposes NSUserDefaults,
-// which is not a trust boundary, so the capability stays unsupported.
+// Native APIs are loaded by the CLI's platforms/macos leaf loader.
 import type { Capability, SecureStore } from './types'
 
+interface NativeSecureStorage {
+	get(key: string): { objectForKey(key: string): unknown }
+	set(options: { key: string; value: string }): boolean
+	remove(key: string): boolean
+}
+
+declare const XplatSecureStorage: NativeSecureStorage | undefined
+const native = () => (typeof XplatSecureStorage === 'undefined' ? null : XplatSecureStorage)
+
+const store: SecureStore = {
+	async get(key) {
+		try {
+			const result = native()?.get(key)
+			if (!result || result.objectForKey('status') === -25300) {
+				return null
+			} // errSecItemNotFound
+
+			const value = result.objectForKey('value')
+			if (result.objectForKey('status') === 0 && typeof value === 'string') {
+				return value
+			}
+		} catch {
+			// Native exceptions may contain arguments. Never forward them.
+		}
+
+		throw new Error('Keychain read failed')
+	},
+	async set(key, value) {
+		try {
+			return native()?.set({ key, value }) ?? false
+		} catch {
+			return false
+		}
+	},
+	async remove(key) {
+		try {
+			return native()?.remove(key) ?? false
+		} catch {
+			return false
+		}
+	},
+}
+
 export const secureStorage: Capability<SecureStore> = {
-	supported: false,
-	ensure: async () => 'unsupported',
-	impl: null,
+	get supported() {
+		return native() !== null
+	},
+	ensure: async () => (native() ? 'granted' : 'unsupported'),
+	get impl() {
+		return native() ? store : null
+	},
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-/** Optional capability — never throws for absence (docs/platform-services.md). */
+/** Optional capability — never throws for absence (docs/platform/platform-services.md). */
 export interface Capability<T> {
 	supported: boolean
 	ensure(): Promise<'granted' | 'denied' | 'unsupported'>

package/types/index.macos.d.ts

@@ -0,0 +1,3 @@
+import type { Capability, SecureStore } from '../src/types.js'
+export type { Capability, SecureStore } from '../src/types.js'
+export declare const secureStorage: Capability<SecureStore>