@octane-xplat/secure-storage 0.0.0-stage → 0.9.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,34 @@
-# Temporary Holding Version
+# `@octane-xplat/secure-storage`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+```
+
+```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')
+}
+```
+
+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`).
+
+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).

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@octane-xplat/secure-storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.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",
+    "directory": "packages/secure-storage"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": "./src/index.macos.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/secure-storage": "4.0.2",
+    "@octane-xplat/platform": "0.9.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "octane": "0.6.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"
+    }
+  },
+  "scripts": {
+    "test:packed": "node tests/packed-consumer.mjs"
+  }
 }

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,9 @@
+// Secure storage — AppKit host leaf. The dev host exposes NSUserDefaults,
+// which is not a trust boundary, so the capability stays unsupported.
+import type { Capability, SecureStore } from './types'
+
+export const secureStorage: Capability<SecureStore> = {
+	supported: false,
+	ensure: async () => 'unsupported',
+	impl: 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-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>
+}