envlock-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Davies
+
+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

@@ -0,0 +1,82 @@
+# envlock-core
+
+Framework-agnostic 1Password + dotenvx secret injection logic.
+
+> Most users should install [`envlock`](https://www.npmjs.com/package/envlock) instead. This package is for integrating envlock with frameworks other than Next.js.
+
+## Install
+
+```bash
+pnpm add envlock-core
+```
+
+## API
+
+### `runWithSecrets(options)`
+
+Runs a command with secrets injected from 1Password via dotenvx. If `DOTENV_PRIVATE_KEY_<ENV>` is already set (e.g. in CI), it skips `op run` and calls `dotenvx run` directly.
+
+```ts
+import { runWithSecrets } from 'envlock-core';
+
+runWithSecrets({
+  envFile: '.env.production',
+  environment: 'production',
+  onePasswordEnvId: 'ca6uypwvab5mevel44gqdc2zae',
+  command: 'node',
+  args: ['server.js'],
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `envFile` | `string` | Path to the encrypted dotenvx env file |
+| `environment` | `string` | Environment name (`development`, `staging`, `production`) |
+| `onePasswordEnvId` | `string` | Your 1Password Environment ID |
+| `command` | `string` | The command to run |
+| `args` | `string[]` | Arguments to pass to the command |
+
+### `validateOnePasswordEnvId(id)`
+
+Throws if `id` is not a valid 1Password Environment ID (lowercase alphanumeric + hyphens). Protects against CLI flag injection and shell metacharacters.
+
+### `validateEnvFilePath(envFile, cwd)`
+
+Throws if `envFile` resolves outside `cwd`. Protects against path traversal.
+
+### `hasBinary(name)`
+
+Returns `true` if `name` is found in `PATH`.
+
+### `checkBinary(name, installHint)`
+
+Calls `process.exit(1)` with a helpful message if `name` is not in `PATH`.
+
+## Types
+
+```ts
+type Environment = 'development' | 'staging' | 'production';
+
+interface EnvlockOptions {
+  onePasswordEnvId: string;
+  envFiles?: {
+    development?: string;
+    staging?: string;
+    production?: string;
+  };
+}
+
+interface RunWithSecretsOptions {
+  envFile: string;
+  environment: string;
+  onePasswordEnvId: string;
+  command: string;
+  args: string[];
+}
+```
+
+## License
+
+MIT — [Benjamin Davies](https://github.com/BenDavies1218)

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+interface RunWithSecretsOptions {
+    envFile: string;
+    environment: string;
+    onePasswordEnvId: string;
+    command: string;
+    args: string[];
+}
+declare function runWithSecrets(options: RunWithSecretsOptions): void;
+
+declare function hasBinary(name: string): boolean;
+declare function checkBinary(name: string, installHint: string): void;
+
+declare function validateOnePasswordEnvId(id: string): void;
+declare function validateEnvFilePath(envFile: string, cwd: string): void;
+
+type Environment = "development" | "staging" | "production";
+interface EnvlockOptions {
+    onePasswordEnvId: string;
+    envFiles?: {
+        development?: string;
+        staging?: string;
+        production?: string;
+    };
+}
+
+export { type Environment, type EnvlockOptions, type RunWithSecretsOptions, checkBinary, hasBinary, runWithSecrets, validateEnvFilePath, validateOnePasswordEnvId };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/invoke.ts
+import { spawnSync } from "child_process";
+
+// src/detect.ts
+import { execFileSync } from "child_process";
+var WHICH = process.platform === "win32" ? "where" : "which";
+function hasBinary(name) {
+  try {
+    execFileSync(WHICH, [name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkBinary(name, installHint) {
+  if (!hasBinary(name)) {
+    console.error(`[envlock] '${name}' not found in PATH.
+${installHint}`);
+    process.exit(1);
+  }
+}
+
+// src/invoke.ts
+function runWithSecrets(options) {
+  const { envFile, environment, onePasswordEnvId, command, args } = options;
+  checkBinary(
+    "dotenvx",
+    "Install dotenvx: npm install -g @dotenvx/dotenvx\nOr add it as a dev dependency."
+  );
+  const privateKeyVar = `DOTENV_PRIVATE_KEY_${environment.toUpperCase()}`;
+  const keyAlreadyInjected = !!process.env[privateKeyVar];
+  let result;
+  if (keyAlreadyInjected) {
+    result = spawnSync(
+      "dotenvx",
+      ["run", "-f", envFile, "--", command, ...args],
+      { stdio: "inherit" }
+    );
+  } else {
+    checkBinary(
+      "op",
+      "Install 1Password CLI: brew install --cask 1password-cli@beta\nThen sign in: op signin"
+    );
+    result = spawnSync(
+      "op",
+      [
+        "run",
+        "--environment",
+        onePasswordEnvId,
+        "--",
+        "dotenvx",
+        "run",
+        "-f",
+        envFile,
+        "--",
+        command,
+        ...args
+      ],
+      { stdio: "inherit" }
+    );
+  }
+  process.exit(result.status ?? 1);
+}
+
+// src/validate.ts
+import { isAbsolute, relative, resolve } from "path";
+var OP_ENV_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function validateOnePasswordEnvId(id) {
+  if (!id || !OP_ENV_ID_PATTERN.test(id)) {
+    throw new Error(
+      `[envlock] Invalid onePasswordEnvId: "${id}". Must be a lowercase alphanumeric string (hyphens allowed), e.g. 'ca6uypwvab5mevel44gqdc2zae'.`
+    );
+  }
+}
+function validateEnvFilePath(envFile, cwd) {
+  if (envFile.includes("\0")) {
+    throw new Error(`[envlock] Invalid env file path: null bytes are not allowed.`);
+  }
+  const resolved = resolve(cwd, envFile);
+  const base = resolve(cwd);
+  const rel = relative(base, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(
+      `[envlock] Invalid env file path: "${envFile}" resolves outside the project directory.`
+    );
+  }
+}
+export {
+  checkBinary,
+  hasBinary,
+  runWithSecrets,
+  validateEnvFilePath,
+  validateOnePasswordEnvId
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "envlock-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Core 1Password + dotenvx secret injection logic for envlock",
+  "license": "MIT",
+  "author": "Benjamin Davies",
+  "homepage": "https://github.com/BenDavies1218/envlock#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BenDavies1218/envlock.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/BenDavies1218/envlock/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}