feat: prepare 0.5.0 release

Author: JoaoPauloCMarra

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report a reproducible Nitro Storage bug.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: Minimal code or repository that reproduces the issue.
+      render: tsx
+    validations:
+      required: true
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Storage scope
+      options:
+        - Memory
+        - Disk
+        - Secure
+        - Web backend
+        - Biometric
+        - Packaging/build
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: react-native-nitro-storage, react-native, react-native-nitro-modules, Expo if used.
+      placeholder: "react-native-nitro-storage 0.5.0, RN 0.83.2, Nitro 0.35.4"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.gitignore

@@ -117,4 +117,7 @@ temp/
 *.md
 !README.md
 !CONTRIBUTING.md
-!CHANGELOG.md
+!CHANGELOG.md
+!SECURITY.md
+!docs/
+!docs/**/*.md

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.5.0 - 2026-04-18
+
+### Added
+
+- Add secure-storage capability metadata with `storage.getSecurityCapabilities()`.
+- Add metadata-only secure key inspection with `storage.getSecureMetadata(key)` and `storage.getAllSecureMetadata()`.
+- Add public `SecurityCapabilities` and `SecureStorageMetadata` types.
+- Add security policy and focused docs for secure storage, React hooks, and MMKV migration.
+
+### Changed
+
+- Refresh README positioning, badges, platform support, security model, storage-library comparison guidance, and benchmark guidance for npm/GitHub discoverability.
+- Tighten README decisioning with an at-a-glance API map, Expo plugin options, bare Android setup, migration paths, and a release checklist.
+- Split detailed usage material into focused docs for API reference, React hooks, secure storage, web backends, batch/transaction/migration workflows, recipes, MMKV migration, and benchmarks.
+- Expand npm package description and keywords around React Native secure storage, biometric storage, Keychain, Android Keystore, Nitro Modules, MMKV migration, Expo SecureStore, Zustand/Jotai, and IndexedDB.
+- Update release tooling patches for `@swc/core`, `@types/node`, and `turbo`.
+
 ## 0.4.5 - 2026-04-14
 
 ### Added

README.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are shipped for the latest published `0.x` release line.
+
+| Version | Supported |
+| ------- | --------- |
+| `0.5.x` | Yes       |
+| `<0.5`  | No        |
+
+## Reporting a Vulnerability
+
+Report security issues through GitHub Security Advisories with:
+
+- affected package version
+- platform and OS version
+- React Native and `react-native-nitro-modules` versions
+- reproduction steps
+- whether the issue affects Memory, Disk, Secure, biometric storage, web backends, or packaging
+
+Do not publish proof-of-concept exploit details until a fix is available.
+
+## Storage Boundary
+
+Native Secure scope delegates encryption to platform storage APIs: iOS Keychain and Android Jetpack Security `EncryptedSharedPreferences`. Web Secure scope is API-compatible but defaults to namespaced `localStorage`; use a custom web secure backend when browser-side storage must meet a stricter threat model.

SECURITY.md

@@ -164,6 +164,12 @@ export default function HomeScreen() {
   const [token, setToken] = useStorage(secureTokenItem);
   const [tempToken, setTempToken] = useState("");
   const tempTokenRef = useRef("");
+  const [secureMetadata, setSecureMetadata] = useState(() =>
+    storage.getSecureMetadata("secure-token"),
+  );
+  const [secureMetadataCount, setSecureMetadataCount] = useState(
+    () => storage.getAllSecureMetadata().length,
+  );
 
   // 4. Namespaces
   const [nsPref, setNsPref] = useStorage(namespacedItem);
@@ -234,6 +240,12 @@ export default function HomeScreen() {
   const [diskBufferedPreview, setDiskBufferedPreview] = useState("(empty)");
   const [classifiedErrorCode, setClassifiedErrorCode] = useState("(none)");
   const capabilities = storage.getCapabilities();
+  const securityCapabilities = storage.getSecurityCapabilities();
+
+  const refreshSecureMetadata = () => {
+    setSecureMetadata(storage.getSecureMetadata("secure-token"));
+    setSecureMetadataCount(storage.getAllSecureMetadata().length);
+  };
 
   return (
     <Page title="Nitro Storage" subtitle="Complete feature showcase">
@@ -356,6 +368,7 @@ export default function HomeScreen() {
               setToken(tempTokenRef.current.trim());
               tempTokenRef.current = "";
               setTempToken("");
+              refreshSecureMetadata();
             }}
             variant="success"
             style={styles.flex1}
@@ -366,6 +379,7 @@ export default function HomeScreen() {
             variant="danger"
             onPress={() => {
               secureTokenItem.delete();
+              refreshSecureMetadata();
             }}
           />
         </View>
@@ -377,6 +391,16 @@ export default function HomeScreen() {
             color={Colors.secure}
           />
         ) : null}
+        <StatusRow
+          testID="secure-metadata-kind"
+          label="Stored as"
+          value={secureMetadata.kind}
+        />
+        <StatusRow
+          testID="secure-metadata-count"
+          label="Secure key inventory"
+          value={String(secureMetadataCount)}
+        />
       </Card>
 
       {/* 4. Namespaces */}
@@ -1034,6 +1058,16 @@ export default function HomeScreen() {
           label="Secure backend"
           value={capabilities.backend.secure}
         />
+        <StatusRow
+          testID="capabilities-secure-encrypted"
+          label="Secure encrypted"
+          value={securityCapabilities.secureStorage.encrypted}
+        />
+        <StatusRow
+          testID="capabilities-biometric-prompt"
+          label="Biometric prompt"
+          value={securityCapabilities.biometric.prompt}
+        />
         <StatusRow
           testID="capabilities-buffering"
           label="Write buffering"

apps/example/app/index.tsx

@@ -428,11 +428,27 @@ function buildTests(): { label: string; fn: TestFn }[] {
       label: "Capabilities / error codes / disk buffering",
       fn: () => {
         const capabilities = storage.getCapabilities();
+        const securityCapabilities = storage.getSecurityCapabilities();
         assert(capabilities.writeBuffering.disk, "disk buffering unavailable");
         assert(
           capabilities.errorClassification,
           "error classification unavailable",
         );
+        assert(
+          securityCapabilities.metadata.listsWithoutValues,
+          "secure metadata inventory unavailable",
+        );
+        storage.setString(
+          "__smoke_secure_meta__",
+          "secret",
+          StorageScope.Secure,
+        );
+        const secureMetadata = storage.getSecureMetadata(
+          "__smoke_secure_meta__",
+        );
+        assert(secureMetadata.exists, "expected secure metadata exists");
+        assert(!secureMetadata.valueExposed, "metadata exposed a secret value");
+        storage.deleteString("__smoke_secure_meta__", StorageScope.Secure);
         assert(
           getStorageErrorCode(
             new Error(