@octane-xplat/secure-storage 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# @octane-xplat/secure-storage
+# `@octane-xplat/secure-storage`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+```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'
+
+// 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')
+}
+```
+
+The shared capability contract: `supported` reports whether an
+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/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,19 +1,85 @@
 {
   "name": "@octane-xplat/secure-storage",
-  "version": "0.0.1",
+  "version": "0.10.0",
   "description": "Keychain/Keystore-backed secure storage for Octane xplat — matching web + NativeScript implementations",
+  "keywords": [
+    "android",
+    "cross-platform",
+    "ios",
+    "keychain",
+    "keystore",
+    "nativescript",
+    "octane",
+    "secure-storage",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/secure-storage",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/secure-storage"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/secure-storage",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "src",
+    "types",
+    "platforms"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/secure-storage": "4.0.2",
+    "@octane-xplat/platform": "0.10.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "octane": "0.6.3",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "xplat": {
+    "macos": {
+      "frameworks": [
+        "Foundation",
+        "Security"
+      ]
+    }
+  },
+  "scripts": {
+    "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/index.macos.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export { secureStorage } from './secure-storage.macos'

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export { secureStorage } from './secure-storage'

package/src/secure-storage.linux.ts

@@ -0,0 +1,2 @@
+// Linux's system webview uses the shared host-aware web implementation.
+export { secureStorage } from './secure-storage.web'

package/src/secure-storage.macos.ts

@@ -0,0 +1,55 @@
+// 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> = {
+	get supported() {
+		return native() !== null
+	},
+	ensure: async () => (native() ? 'granted' : 'unsupported'),
+	get impl() {
+		return native() ? store : null
+	},
+}

package/src/secure-storage.ts

@@ -0,0 +1,17 @@
+// Secure storage — Keychain (iOS) / Keystore (Android) via plugin.
+import { SecureStorage } from '@nativescript/secure-storage'
+import type { Capability } from './types'
+import type { SecureStore } from './types'
+
+const store = new SecureStorage()
+
+export const secureStorage: Capability<SecureStore> = {
+	supported: true,
+	// No runtime permission needed — Keychain/Keystore is device-owned.
+	ensure: async () => 'granted',
+	impl: {
+		get: (key) => store.get({ key }).then((v) => v ?? null),
+		set: (key, value) => store.set({ key, value }),
+		remove: (key) => store.remove({ key }),
+	},
+}

package/src/secure-storage.web.ts

@@ -0,0 +1,23 @@
+// Secure storage — plain web has no equivalent trust boundary. Desktop
+// webview hosts can provide one through the typed host bridge.
+import { desktopHost } from '@octane-xplat/platform/host/web'
+import type { Capability, SecureStore } from './types'
+
+const hostStore: SecureStore = {
+	get: (key) => desktopHost()?.secureStorage.get(key) ?? Promise.resolve(null),
+	set: (key, value) => desktopHost()?.secureStorage.set(key, value) ?? Promise.resolve(false),
+	remove: (key) => desktopHost()?.secureStorage.remove(key) ?? Promise.resolve(false),
+}
+
+export const secureStorage: Capability<SecureStore> = {
+	get supported() {
+		return desktopHost() !== null
+	},
+	async ensure() {
+		const host = desktopHost()
+		return host && (await host.supports('secureStorage', 'get')) ? 'granted' : 'unsupported'
+	},
+	get impl() {
+		return desktopHost() ? hostStore : null
+	},
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+/** Optional capability — never throws for absence (docs/platform/platform-services.md). */
+export interface Capability<T> {
+	supported: boolean
+	ensure(): Promise<'granted' | 'denied' | 'unsupported'>
+	/** usable iff supported && ensured */
+	impl: T | null
+}
+
+export interface SecureStore {
+	get(key: string): Promise<string | null>
+	set(key: string, value: string): Promise<boolean>
+	remove(key: string): Promise<boolean>
+}

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>

package/index.d.ts

@@ -1 +0,0 @@
-export {}

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}