Merge pull request #6 from AegisJSProject/feature/file-import

Add `openSecretStoreFile` to open secret store from JSON file (node)

Author: shgysk8zer0

.npmignore

@@ -1,4 +1,6 @@
 node_modules/
+secrets.json
+key.jwk
 test/
 .github/
 test/

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v1.0.1] - 2025-09-04
+
+### Added
+- Add `openSecretStoreFile` to open secret store from JSON file (node)
+
 ## [v1.0.0] - 2025-09-04
 
 Initial Release

README.md

@@ -16,7 +16,7 @@ Proxy-based wrapper for encrypting and decrypting data over any storage object
 ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40aegisjsproject%secret-store)
 [![npm](https://img.shields.io/npm/dw/@aegisjsproject/secret-store?logo=npm)](https://www.npmjs.com/package/@aegisjsproject/secret-store)
 
-[![GitHub followers](https://img.shields.io/github/followers/AegisJSProject.svg?style=social)](https://github.com/AegisJSProoject)
+[![GitHub followers](https://img.shields.io/github/followers/AegisJSProject.svg?style=social)](https://github.com/AegisJSProject)
 ![GitHub forks](https://img.shields.io/github/forks/AegisJSProject/secret-store.svg?style=social)
 ![GitHub stars](https://img.shields.io/github/stars/AegisJSProject/secret-store.svg?style=social)
 [![Twitter Follow](https://img.shields.io/twitter/follow/shgysk8zer0.svg?style=social)](https://twitter.com/shgysk8zer0)
@@ -28,125 +28,73 @@ Proxy-based wrapper for encrypting and decrypting data over any storage object
 - [Contributing](./.github/CONTRIBUTING.md)
 <!-- - [Security Policy](./.github/SECURITY.md) -->
 
-This is a [GitHub Template Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)
-to create components using [`@aegisjsproject/component`](https://npmjs.com/package/@aegisjsproject/component).
-It serves as a quick-start to creating light-weight, secure, web standards based 
-components. It provides the essentials, such as:
+## Installation
 
-- The essential packages:
-  - [`@aegisjsproject/core`](https://github.com/AegisJSProject/aegis)
-  - [`@aegisjsproject/styles`](https://github.com/AegisJSProject/styles)
-  - [`@aegisjsproject/component`](https://github.com/AegisJSProject/component)
-- Build tools
-  - [eslint](https://npmjs.com/eslint)
-  - [rollup](https://npmjs.com/rollup)
-- [Dependabot](https://github.com/dependabot) & [CodeQL](https://github.com/github/codeql) config
-- Pull Request & Issue templates
-- Automated releases to npm on `git tag` (when pushed using `git push --tags`)
-- Provides GitHub Action for Package Provenance
+### npm
+```bash
+npm install @aegisjsproject/secret-store
+```
 
-To start creating your own component, just go to the [GitHub repo](https://@github.com/AegisJSProject/secret-store)
-and click the "Use this template" button.
+### `<script type="importmap">`
 
-## Steps to Create a Component
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@aegisjsproject/secret-store": "https://unpkg.com/@aegisjsproject/secret-store/secret-store.min.js",
+    "@shgysk8zer0/aes-gcm": "https://unpkg.com/@shgysk8zer0/aes-gcm/aes-gcm.min.js"
+  }
+}
+</script>
+```
 
-- Create Repository from the GitHub Template Repository
-- Clone your new Aegis Component Repository
-- Update the `README.md`, `package.json`, & `CHANGELOG.md` as needed (especially the name)
-- Create your component
-- Update `rollup.config.js` (don't forget to update `input` & `output.file`)
-- Publish (create and merge PR)
+## API
 
-## Using Automated Releases
+### `useSecretStore(key, targetObject, handler)`
 
-The following  setup will create an automated GitHub Release and publish on npm
-for every signed git tag (`git tag -s vx.y.z`) pushed to GitHub:
+Creates an encrypted proxy around an object where values are automatically encrypted on set and decrypted on get.
 
-- Create a "Classic Token" (Automation) on [npmjs.org](https://www.npmjs.com/)
-- Give that token a descriptive name name and copy it
-- Paste it into your repository's "Repository secrets" in "settings" -> "Secrets and variables" -> Actions
-- Done!
+**Parameters:**
+- `key` - CryptoKey with decrypt usage (encrypt usage required for setter)
+- `targetObject` - Object to wrap (defaults to `process.env`)
+- `handler` - ProxyHandler (defaults to `Reflect`)
 
-Now, every time you create a new PGP signed tag on GitHub (don't forget to `git push --tags`)
-it will create a new GitHub Release and a new release on npm with Package Provenance.
+**Returns:** `[proxy, setter]` - Frozen array containing the proxy and async setter function
 
-## Example Component:
+**Throws:** TypeError if key lacks decrypt usage
 
-```js
-import { AegisComponent, SYMBOLS, TRIGGERS } from '@aegisjsproject/component';
-import { html, appendTo } from '@aegisjsproject/core';
-
-class HTMLHelloWorldElement extends AegisComponent {
-  async [SYMBOLS.render](type, { shadow }) {
-    switch(type) {
-      case TRIGGERS.constructed:
-        appendTo(shadow, html`<h1>Hello, World!</h1>`);
-        break;
-    }
-  }
-}
+### `openSecretStoreFile(key, path, config)`
 
-HTMLHelloWorldElement.register('hello-world');
-```
+Node.js only. Loads and wraps a JSON file as an encrypted store.
 
-## Package, Component, & Repository Requirements
+**Parameters:**
+- `key` - CryptoKey 
+- `path` - File path string
+- `config.encoding` - File encoding (default: "utf8")
+- `config.handler` - ProxyHandler (default: `Reflect`)
+- `config.signal` - AbortSignal for cancellation
 
-All packages **MUST** adhere to strict but fairly easy security guidelines:
+**Returns:** Promise resolving to `[proxy, setter]`
 
-- All commits and tags **MUST** be [PGP/GPG signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
-- All web-based commits **MUST** be signed off by the contributor (a setting in GitHub repo settings)
-- All releases **MUST** use [Package Provenance](https://github.blog/2023-04-19-introducing-npm-package-provenance/)
-- Components **MUST** adhere to a strict [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
-- Components **MUST** comply with the provided [`TrustedTypesPolicy`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy) or add their own, which **SHOULD**:
-  - Use `:component-name#html` for writing HTML as a string
-  - Use `:component-name#script-url`
-- Components **MUST** be `import`able from a CDN (such as `unpkg.com`) without any build step/bundler
-- Component **SHOULD** provide a `<script type="importmap">` or `importmap.json` as necessary
-- Components **MUST NOT** use inline scripts (`script-src 'unsafe-inline`) or styles (`style-src 'unsafe-inline'`)
-- Components **MUST NOT** use `element.innerHTML` or similar
-- Components **MUST NOT** use `eval()` or `onclick` or anything similar
-- Components using [life cycle callbacks](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_the_lifecycle_callbacks) **MUST** have a `[Symbol.for('aegis:render')]` method
+## Usage
 
-## Content-Security-Policy
+```js
+import { useSecretStore, openSecretStoreFile } from '@aegisjsproject/secret-store';
 
-This is the base CSP (with comments):
+// Generate key
+const key = await crypto.subtle.generateKey(
+  { name: 'AES-GCM', length: 256 },
+  false,
+  ['encrypt', 'decrypt']
+);
 
-```
-default-src 'none'; // Block everything by default
-style-src 'self' blob:; // `blob:` essential for constructable stylesheet polyfill
-script-src 'self' https://unpkg.com/@aegisjsproject/; // Your script source may/should be added
-connect-src 'self'; // Add any data sources as needed, but as specific as possible
-trusted-types emtpy#html mepty#script sanitizer-raw#html; // Add to as necessary
-require-trusted-types-for 'script'; // This is required and currently the only option
-```
+// Create store
+const [store, set] = useSecretStore(key, {});
+
+// Values are encrypted when set, decrypted when accessed
+await set('password', 'secret123');
+const password = await store.password; // 'secret123'
 
-Components **MAY** differ from this in requiring additional `script-src` (other
-than `unnsafe-inline`, `unsafe-eval`, and additional `nonce-*` or `sha*` hashes
-(URL only permitted). Components **MAY** add to the `trusted-types`, if necessary,
-such as to add additional [`policy.createScriptURL()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScript)s
-as essential. Any such policy created for script URLs (namely, `<iframe>`s)
-**SHOULD** be of the form `:component-name#script-url`.
-
-Components **SHOULD NOT** utilize methods or setters (such as `innerHTML`) which
-write HTML as strings and would require [`policy.createHTML()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createHTML).
-Components **MAY** use the text alternatives, such as `textContent`. However,
- should the component require such things, the component **MUST** create an
-additional `TrsutedTypePolicy`, which **SHOULD** be named as `:component-name#html`:
-
-Components **SHOULD NOT** include any [`policy.createScript()`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScript)
-unless absolutely essential, as this would violate the strict CSP requirement and
-restriction from using `unsafe-*` in `script-src`. However, should your component
-absolutely and justifiably require this, it **SHOULD** use a `TrustedTypes` Policy
-name of the form `:component-name#script`.
-
-Any component which requires more than one of `createHTML()`, `createScriptURL()`,
-or `createScript()` **MAY** instead combine the above simple into a single policy,
-which **SHOULD** be named `:component-name`.
-
-Components **MUST** explicitly list any necessary changes to their CSP (including)
-`TrustedTypes` in their README.
-
-To be listed in the upcoming Aegis component registry, components **MUST NOT**
-implement their own `createHTML()` (`:component-name#html`) or `createScript()`
-(`component-name#script`) methods, but **MAY** implement a `createScriptURL()`
-(`:component-name#script-url`) method.
+// Load from file (Node.js)
+const [fileStore] = await openSecretStoreFile(key, './secrets.json');
+```

key.jwk

@@ -0,0 +1 @@
+{"key_ops":["encrypt","decrypt"],"ext":true,"kty":"oct","k":"sehAb7rHKUE-w_6rYA_XqZaaLc70d8fCXe-JLwe-OCU","alg":"A256GCM"}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@aegisjsproject/secret-store",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Proxy-based wrapper for encrypting and decrypting data over any storage object",
   "keywords": [
     "aegis",

package.json

@@ -1,5 +1,5 @@
 import terser from '@rollup/plugin-terser';
-const externalPackages = ['@shgysk8zer0/aes-gcm'];
+const externalPackages = ['@shgysk8zer0/aes-gcm', 'node:'];
 
 export default {
 	input: 'secret-store.js',

rollup.config.js

@@ -46,3 +46,35 @@ export function useSecretStore(key, targetObject = globalThis.process?.env ?? {}
 		return Object.freeze([proxy, setter]);
 	}
 }
+
+/**
+ * Opens a secret store from a JSON file. (Node only)
+ *
+ * @param {CryptoKey} key
+ * @param {string} path
+ * @param {object} config
+ * @param {string} [config.encoding="utf8"]
+ * @param {ProxyHandler} [config.handler=Reflect]
+ * @param {AbortSignal} [config.signal]
+ * @returns {Promise<[Proxy, (prop, val) => Promise<boolean>]>}
+ * @throws {*} Any `signal.reason` and an aborted `AbortSignal`.
+ * @throws {TypeError} If `key` is not a `CryptoKey`.
+ * @throws {TypeError} If `path` is not a string/path.
+ * @throws {Error} Any error from `readFile` or `JSON.parse` or `useSecretStore`.
+ */
+export async function openSecretStoreFile(key, path, { encoding = 'utf8', handler = Reflect, signal  } = {}) {
+	if (signal instanceof AbortSignal && signal.aborted) {
+		throw signal.reason;
+	} else if (! (key instanceof CryptoKey)) {
+		throw new TypeError('Key must be a `CryptoKey`.');
+	} else if (typeof path !== 'string') {
+		throw new TypeError('Path must be a string.');
+	} else {
+		// Using this to keep the rest of the module compatible in other environments
+		const { readFile } = await import('node:fs/promises');
+		const text = await readFile(path, { encoding, signal });
+		const data = JSON.parse(text);
+
+		return useSecretStore(key, data, handler);
+	}
+}

secret-store.js

@@ -1,9 +1,15 @@
 import '@shgysk8zer0/polyfills';
 
 import { generateSecretKey } from '@shgysk8zer0/aes-gcm';
-import { useSecretStore } from './secret-store.js';
+import { useSecretStore, openSecretStoreFile } from './secret-store.js';
 import { test, describe } from 'node:test';
 import { strictEqual, deepEqual, throws, rejects, doesNotReject, ok, notStrictEqual } from 'node:assert';
+import { readFile } from 'node:fs/promises';
+
+async function getKey({ signal } = {}) {
+	const keyData = await readFile('key.jwk', { encoding: 'utf8', signal });
+	return await crypto.subtle.importKey('jwk', JSON.parse(keyData), 'AES-GCM', false, ['decrypt', 'encrypt']);
+}
 
 describe('Test encrypted storage', async () => {
 	test('Check the things', async () => {
@@ -41,6 +47,16 @@ describe('Test encrypted storage', async () => {
 		await promise;
 	});
 
+	test('Check file version of secret store', async () => {
+		const key = await getKey();
+		const [store] = await openSecretStoreFile(key, 'secrets.json');
+		strictEqual(await store.msg, 'Hello, World!', 'Should open secrets file and decrypt correctly.');
+
+		rejects(() => openSecretStoreFile([]), 'Should reject when not given a `CryptoKey`.');
+		rejects(() => openSecretStoreFile(key, []), 'Should reject when not given a string for a file path.');
+		rejects(() => openSecretStoreFile(key, 'secrets.json', { signal: AbortSignal.abort('Make me fail!')}), 'Should reject when given an aborted `AbortSignal`.');
+	});
+
 	test('Check for things that should error.', async () => {
 		const encryptKey = await generateSecretKey({ usages: ['encrypt'] });
 		const decryptKey = await generateSecretKey({ usages: ['decrypt'] });

secret-store.test.js

@@ -0,0 +1,3 @@
+{
+  "msg": "HHaIpdhZQRkqzEzgZ4QVpsVgJyPQvwS6L69EXwwh+m+QqUSvxsee7/I="
+}