@symbiote-native/secure-store 0.0.1

package/build-ngc/core/secure-store.js

@@ -0,0 +1,138 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoSecureStore } from './native-module';
+const NATIVE_MODULE_NAME = 'expo-secure-store';
+// Alphanumerics plus ".", "-" and "_": the same set the native side validates against, so an
+// invalid key fails here with a readable message instead of deep inside the keychain call.
+const VALID_KEY_PATTERN = /^[\w.-]+$/;
+/**
+ * The item cannot be read after a restart until the device has been unlocked once. Useful for
+ * data the app needs while the phone is locked.
+ * @platform ios
+ */
+export const AFTER_FIRST_UNLOCK = expoSecureStore.AFTER_FIRST_UNLOCK;
+/**
+ * Like `AFTER_FIRST_UNLOCK`, except the entry does not migrate to a new device when restoring
+ * from a backup.
+ * @platform ios
+ */
+export const AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY = expoSecureStore.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY;
+/**
+ * The item can always be read, locked device or not. The least secure option.
+ * @deprecated Use a level that offers some user protection, such as `AFTER_FIRST_UNLOCK`.
+ * @platform ios
+ */
+export const ALWAYS = expoSecureStore.ALWAYS;
+/**
+ * Like `ALWAYS`, except the entry does not migrate to a new device when restoring from a backup.
+ * @deprecated Use a level that offers some user protection, such as
+ * `AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY`.
+ * @platform ios
+ */
+export const ALWAYS_THIS_DEVICE_ONLY = expoSecureStore.ALWAYS_THIS_DEVICE_ONLY;
+/**
+ * Like `WHEN_UNLOCKED_THIS_DEVICE_ONLY`, except the user must have set a passcode to store an
+ * entry at all. Removing the passcode deletes the entry.
+ * @platform ios
+ */
+export const WHEN_PASSCODE_SET_THIS_DEVICE_ONLY = expoSecureStore.WHEN_PASSCODE_SET_THIS_DEVICE_ONLY;
+/**
+ * The item can only be read while the device is unlocked.
+ * @platform ios
+ */
+export const WHEN_UNLOCKED = expoSecureStore.WHEN_UNLOCKED;
+/**
+ * Like `WHEN_UNLOCKED`, except the entry does not migrate to a new device when restoring from a
+ * backup.
+ * @platform ios
+ */
+export const WHEN_UNLOCKED_THIS_DEVICE_ONLY = expoSecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
+/**
+ * Whether the SecureStore API is usable on this device. Says nothing about app permissions.
+ * Resolves `true` on Android and iOS.
+ */
+export async function isAvailableAsync() {
+    return !!expoSecureStore.getValueWithKeyAsync;
+}
+/**
+ * Read the value stored under `key`.
+ *
+ * Resolves `null` when there is no entry for the key, or when the key has been invalidated —
+ * the system invalidates keys stored with `requireAuthentication` whenever enrolled biometrics
+ * change (a new fingerprint, a re-registered face), and an invalidated value can never be read
+ * again. Rejects if reading itself fails.
+ */
+export async function getItemAsync(key, options = {}) {
+    ensureValidKey(key);
+    if (!expoSecureStore.getValueWithKeyAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getItemAsync');
+    }
+    return expoSecureStore.getValueWithKeyAsync(key, options);
+}
+/**
+ * Read the value stored under `key`, synchronously.
+ *
+ * > Blocks the JavaScript thread. With `requireAuthentication` on, the app stays unresponsive
+ * > until the user authenticates.
+ */
+export function getItem(key, options = {}) {
+    ensureValidKey(key);
+    if (!expoSecureStore.getValueWithKeySync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getItem');
+    }
+    return expoSecureStore.getValueWithKeySync(key, options);
+}
+/**
+ * Store a key–value pair. Keys may contain alphanumeric characters, `.`, `-` and `_`.
+ * Rejects if the value cannot be stored on the device.
+ */
+export async function setItemAsync(key, value, options = {}) {
+    ensureValidKey(key);
+    ensureValidValue(value);
+    if (!expoSecureStore.setValueWithKeyAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setItemAsync');
+    }
+    await expoSecureStore.setValueWithKeyAsync(value, key, options);
+}
+/**
+ * Store a key–value pair, synchronously.
+ *
+ * > Blocks the JavaScript thread. With `requireAuthentication` on, the app stays unresponsive
+ * > until the user authenticates.
+ */
+export function setItem(key, value, options = {}) {
+    ensureValidKey(key);
+    ensureValidValue(value);
+    if (!expoSecureStore.setValueWithKeySync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setItem');
+    }
+    expoSecureStore.setValueWithKeySync(value, key, options);
+}
+/** Delete the value stored under `key`. Rejects if the value cannot be deleted. */
+export async function deleteItemAsync(key, options = {}) {
+    ensureValidKey(key);
+    if (!expoSecureStore.deleteValueWithKeyAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'deleteItemAsync');
+    }
+    await expoSecureStore.deleteValueWithKeyAsync(key, options);
+}
+/**
+ * Whether a value can be stored with `requireAuthentication` — `true` when the device supports
+ * biometric authentication and the enrolled method is strong enough.
+ */
+export function canUseBiometricAuthentication() {
+    if (!expoSecureStore.canUseBiometricAuthentication) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'canUseBiometricAuthentication');
+    }
+    return expoSecureStore.canUseBiometricAuthentication();
+}
+function ensureValidKey(key) {
+    if (typeof key !== 'string' || !VALID_KEY_PATTERN.test(key)) {
+        throw new Error('Invalid key provided to SecureStore. Keys must not be empty and contain only alphanumeric characters, ".", "-", and "_".');
+    }
+}
+function ensureValidValue(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Invalid value provided to SecureStore. Values must be strings; consider JSON-encoding your values if they are serializable.');
+    }
+}
+//# sourceMappingURL=secure-store.js.map

package/build-ngc/core/secure-store.js.map

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

package/build-ngc/core/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * An iOS [`kSecAttrAccessible`](https://developer.apple.com/documentation/security/ksecattraccessible/)
+ * value, as exposed by the native module. Opaque on purpose — pass one of the constants this
+ * package exports rather than a literal.
+ */
+export type IKeychainAccessibilityConstant = number;
+export type ISecureStoreOptions = {
+    /**
+     * - Android: equivalent of the public/private key pair `Alias`.
+     * - iOS: the item's service, equivalent to [`kSecAttrService`](https://developer.apple.com/documentation/security/ksecattrservice/).
+     *
+     * An item stored with a `keychainService` needs the same one to be read back.
+     */
+    keychainService?: string;
+    /**
+     * Require the device's own authentication (biometrics or passcode) to reach the stored value.
+     * - Android: [`setUserAuthenticationRequired(true)`](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean)).
+     * - iOS: [`biometryCurrentSet`](https://developer.apple.com/documentation/security/secaccesscontrolcreateflags/2937192-biometrycurrentset).
+     *
+     * The two platforms prompt at different moments: Android authenticates on every operation,
+     * iOS only when reading or updating an existing value, never when creating one. The full
+     * behavior needs a freshly generated key, so it does not combine with a `keychainService`
+     * already used for non-authenticated entries.
+     *
+     * > Emulators and simulators do not enforce the prompt when retrieving a secret — testing this
+     * > option means testing on a real device.
+     */
+    requireAuthentication?: boolean;
+    /** Message shown to the user in the prompt raised by `requireAuthentication`. */
+    authenticationPrompt?: string;
+    /**
+     * When the stored entry is accessible, via iOS's `kSecAttrAccessible` property.
+     * @default WHEN_UNLOCKED
+     * @platform ios
+     */
+    keychainAccessible?: IKeychainAccessibilityConstant;
+    /**
+     * The [access group](https://developer.apple.com/documentation/security/sharing-access-to-keychain-items-among-a-collection-of-apps)
+     * the stored entry belongs to.
+     * @platform ios
+     */
+    accessGroup?: string;
+};

package/build-ngc/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build-ngc/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":""}

package/native-link.json

@@ -0,0 +1,21 @@
+{
+  "android": {
+    "gradleProjectName": "expo-secure-store",
+    "modules": [
+      {
+        "importPath": "expo.modules.securestore.SecureStoreModule",
+        "className": "SecureStoreModule",
+        "nativeName": "ExpoSecureStore"
+      }
+    ],
+    "manifestApplicationAttributes": {
+      "android:fullBackupContent": "@xml/secure_store_backup_rules",
+      "android:dataExtractionRules": "@xml/secure_store_data_extraction_rules"
+    }
+  },
+  "ios": {
+    "infoPlistKeys": {
+      "NSFaceIDUsageDescription": "This app uses Face ID to unlock your stored credentials."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@symbiote-native/secure-store",
+  "version": "0.0.1",
+  "description": "expo-secure-store wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters. Encrypted key-value storage in the iOS Keychain and the Android Keystore, optionally gated behind biometrics.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/secure-store"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/secure-store#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-secure-store": "57.0.1",
+    "expo-modules-core": "57.0.5"
+  },
+  "peerDependencies": {
+    "@symbiote-native/engine": ">=0.1.7",
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "vue": ">=3.5.0",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/vue": "0.3.8"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "^22",
+    "@angular/compiler-cli": "^22",
+    "@angular/core": "^22",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "typescript": "~6.0.0",
+    "@symbiote-native/engine": "0.1.7",
+    "@symbiote-native/test-utils": "0.1.6",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/vue": "0.3.8"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/secure-store/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';

package/src/core/index.ts

@@ -0,0 +1,17 @@
+export {
+  AFTER_FIRST_UNLOCK,
+  AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY,
+  ALWAYS,
+  ALWAYS_THIS_DEVICE_ONLY,
+  WHEN_PASSCODE_SET_THIS_DEVICE_ONLY,
+  WHEN_UNLOCKED,
+  WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+  isAvailableAsync,
+  getItemAsync,
+  getItem,
+  setItemAsync,
+  setItem,
+  deleteItemAsync,
+  canUseBiometricAuthentication,
+} from './secure-store';
+export type { IKeychainAccessibilityConstant, ISecureStoreOptions } from './types';

package/src/core/native-module.ts

@@ -0,0 +1,31 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { IKeychainAccessibilityConstant, ISecureStoreOptions } from './types';
+
+const EXPO_SECURE_STORE_MODULE_NAME = 'ExpoSecureStore';
+
+// Every member is optional — each call site checks for its presence before calling through and
+// throws an UnavailabilityError itself, matching upstream's own per-platform capability checks
+// rather than assuming the native module implements the whole surface.
+//
+// The seven accessibility constants are genuinely iOS-only: Android's SecureStoreModule declares
+// no Constant() at all, so they read `undefined` there. That is why the exported constants carry
+// `| undefined` — they are only ever passed back into an option iOS reads.
+export type INativeSecureStoreModule = {
+  AFTER_FIRST_UNLOCK?: IKeychainAccessibilityConstant;
+  AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY?: IKeychainAccessibilityConstant;
+  ALWAYS?: IKeychainAccessibilityConstant;
+  ALWAYS_THIS_DEVICE_ONLY?: IKeychainAccessibilityConstant;
+  WHEN_PASSCODE_SET_THIS_DEVICE_ONLY?: IKeychainAccessibilityConstant;
+  WHEN_UNLOCKED?: IKeychainAccessibilityConstant;
+  WHEN_UNLOCKED_THIS_DEVICE_ONLY?: IKeychainAccessibilityConstant;
+  getValueWithKeyAsync?(key: string, options: ISecureStoreOptions): Promise<string | null>;
+  getValueWithKeySync?(key: string, options: ISecureStoreOptions): string | null;
+  setValueWithKeyAsync?(value: string, key: string, options: ISecureStoreOptions): Promise<boolean>;
+  setValueWithKeySync?(value: string, key: string, options: ISecureStoreOptions): boolean;
+  deleteValueWithKeyAsync?(key: string, options: ISecureStoreOptions): Promise<void>;
+  canUseBiometricAuthentication?(): boolean;
+};
+
+export const expoSecureStore = requireNativeModule<INativeSecureStoreModule>(
+  EXPO_SECURE_STORE_MODULE_NAME,
+);

package/src/core/secure-store.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_SECURE_STORE = {
+  AFTER_FIRST_UNLOCK: 1,
+  WHEN_UNLOCKED: 5,
+  getValueWithKeyAsync: vi.fn(async () => 'stored'),
+  getValueWithKeySync: vi.fn(() => 'stored'),
+  setValueWithKeyAsync: vi.fn(async () => true),
+  setValueWithKeySync: vi.fn(() => true),
+  deleteValueWithKeyAsync: vi.fn(async () => undefined),
+  canUseBiometricAuthentication: vi.fn(() => true),
+};
+
+// The real ExpoSecureStore native module only exists on device — resolving it via
+// requireNativeModule() at import time would throw in this headless run, so the module-lookup
+// file is faked in place of expo-modules-core's runtime resolution, the same pattern
+// packages/local-auth/src/core/local-authentication.test.ts uses.
+vi.mock('./native-module', () => ({
+  expoSecureStore: FAKE_NATIVE_SECURE_STORE,
+}));
+
+// expo-modules-core's real entry transitively imports 'react-native', whose Flow-typed source
+// Vitest's Oxc transform can't parse — so only the members used as values are faked.
+vi.mock('expo-modules-core', () => ({
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, propertyName: string) {
+      super(`${propertyName} is not available on ${moduleName}`);
+    }
+  },
+}));
+
+const {
+  AFTER_FIRST_UNLOCK,
+  WHEN_UNLOCKED,
+  isAvailableAsync,
+  getItemAsync,
+  getItem,
+  setItemAsync,
+  setItem,
+  deleteItemAsync,
+  canUseBiometricAuthentication,
+} = await import('./secure-store');
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('keychain accessibility constants', () => {
+  it('come from the native module rather than being hardcoded', () => {
+    expect(AFTER_FIRST_UNLOCK).toBe(1);
+    expect(WHEN_UNLOCKED).toBe(5);
+  });
+});
+
+describe('isAvailableAsync', () => {
+  it('reports availability from the presence of the native read method', async () => {
+    await expect(isAvailableAsync()).resolves.toBe(true);
+  });
+});
+
+describe('getItemAsync', () => {
+  it('passes the key and options straight through', async () => {
+    await expect(getItemAsync('token', { keychainService: 'auth' })).resolves.toBe('stored');
+    expect(FAKE_NATIVE_SECURE_STORE.getValueWithKeyAsync).toHaveBeenCalledWith('token', {
+      keychainService: 'auth',
+    });
+  });
+
+  it('defaults the options to an empty object', async () => {
+    await getItemAsync('token');
+    expect(FAKE_NATIVE_SECURE_STORE.getValueWithKeyAsync).toHaveBeenCalledWith('token', {});
+  });
+
+  it('throws an UnavailabilityError-shaped error when the native method is absent', async () => {
+    const { getValueWithKeyAsync: native } = FAKE_NATIVE_SECURE_STORE;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SECURE_STORE.getValueWithKeyAsync = undefined;
+
+    await expect(getItemAsync('token')).rejects.toThrow(
+      'getItemAsync is not available on expo-secure-store',
+    );
+
+    FAKE_NATIVE_SECURE_STORE.getValueWithKeyAsync = native;
+  });
+});
+
+describe('setItemAsync', () => {
+  it('passes value, key and options in the native argument order', async () => {
+    await setItemAsync('token', 'secret', { requireAuthentication: true });
+    expect(FAKE_NATIVE_SECURE_STORE.setValueWithKeyAsync).toHaveBeenCalledWith('secret', 'token', {
+      requireAuthentication: true,
+    });
+  });
+});
+
+describe('the synchronous pair', () => {
+  it('reads and writes through the sync native methods', () => {
+    expect(getItem('token')).toBe('stored');
+    setItem('token', 'secret');
+    expect(FAKE_NATIVE_SECURE_STORE.getValueWithKeySync).toHaveBeenCalledWith('token', {});
+    expect(FAKE_NATIVE_SECURE_STORE.setValueWithKeySync).toHaveBeenCalledWith(
+      'secret',
+      'token',
+      {},
+    );
+  });
+});
+
+describe('deleteItemAsync', () => {
+  it('delegates to the native module', async () => {
+    await deleteItemAsync('token');
+    expect(FAKE_NATIVE_SECURE_STORE.deleteValueWithKeyAsync).toHaveBeenCalledWith('token', {});
+  });
+});
+
+describe('canUseBiometricAuthentication', () => {
+  it('delegates to the native module', () => {
+    expect(canUseBiometricAuthentication()).toBe(true);
+  });
+});
+
+// Validation happens before the native call so a bad key fails with a readable message here
+// rather than deep inside the keychain, and the native module is never handed junk.
+describe('key and value validation', () => {
+  it.each([
+    ['', 'empty'],
+    ['has space', 'a space'],
+    ['sla/sh', 'a slash'],
+    ['💥', 'an emoji'],
+  ])('rejects %j (%s)', async key => {
+    await expect(getItemAsync(key)).rejects.toThrow(/Invalid key provided to SecureStore/);
+    expect(FAKE_NATIVE_SECURE_STORE.getValueWithKeyAsync).not.toHaveBeenCalled();
+  });
+
+  it.each(['token', 'com.example.token', 'my-token', 'my_token'])('accepts %j', async key => {
+    await expect(getItemAsync(key)).resolves.toBe('stored');
+  });
+
+  it('rejects a non-string value before reaching the native module', async () => {
+    // @ts-expect-error -- the guard exists precisely for callers without type checking
+    await expect(setItemAsync('token', { a: 1 })).rejects.toThrow(
+      /Values must be strings; consider JSON-encoding/,
+    );
+    expect(FAKE_NATIVE_SECURE_STORE.setValueWithKeyAsync).not.toHaveBeenCalled();
+  });
+});