sops-age

sops-age is a TypeScript library designed to decrypt files encrypted with SOPS (Secrets OPerationS) and the age encryption tool. This library provides an easy way to decrypt environment variables, configuration files, and other sensitive data encrypted with SOPS and age in your applications. It works in most JavaScript runtimes (node.js, the browser, Deno, Bun, etc).

Features

- Supports decryption of SOPS files encrypted with age
- Automatic age key discovery, following SOPS conventions
- SSH key support, automatically converting Ed25519 and RSA SSH keys to age format
- Compatible with various file formats including .env, .json, and .yaml
- Supports multiple input types (string, Buffer, File, Blob, streams, etc.)
- Works across different JavaScript runtimes (Node.js, Deno, Bun, browser)
- Simple, unified API for decrypting SOPS data from files, URLs, or raw content
- Automatic file type detection with optional manual override

Installation

Install sops-age using your preferred package manager:

``sh


npm

npm install sops-age

pnpm

pnpm add sops-age

yarn

yarn add sops-age
`

Usage

The library can be used in various JavaScript environments and supports multiple module formats:

$3

`js
import { decryptSops } from "sops-age";

// Decrypt from a local file (keys auto-discovered from env and file system)
const config = await decryptSops({
path: "./config.enc.json",
});

// Or with explicit age key
const config = await decryptSops({
path: "./config.enc.json",
secretKey: "AGE-SECRET-KEY-1qgdy...",
});
`

$3

`js
const { decryptSops } = require("sops-age");

// Decrypt from a URL
const config = await decryptSops({
url: "https://example.com/config.enc.yaml",
secretKey: "AGE-SECRET-KEY-1qgdy...",
});
`

$3

`html




`

$3

The library includes TypeScript type definitions:

`ts
import { decryptSops, type DecryptSopsOptions } from "sops-age";

const options: DecryptSopsOptions = {
secretKey: "AGE-SECRET-KEY-1qgdy...",
fileType: "json",
};

const config = await decryptSops(jsonString, options);
`

$3

The library provides a unified decryptSops function that can handle various input types:

`js
import { decryptSops } from "sops-age";

// Decrypt from a local file, auto-discovering age keys
const config = await decryptSops({
path: "./config.enc.json",
});

// Decrypt from a URL with explicit age key
const remoteConfig = await decryptSops({
url: "https://example.com/config.enc.yaml",
secretKey: "AGE-SECRET-KEY-1qgdy...",
});

// Decrypt from string content
const content = '{"sops": {...}}';
const data = await decryptSops(content, {
secretKey: "AGE-SECRET-KEY-1qgdy...",
fileType: "json",
});
`

$3

sops-age supports the following file types:

- .env
- .json
- .yaml / .yml

The library automatically detects the file type based on file extension or content. You can also manually specify the file type using the fileType option.

Input Types

sops-age supports various input types for the SOPS-encrypted content:

- string: Raw string content of a SOPS file
- File: File object (in browser environments)
- Blob: Binary data
- ArrayBuffer: Raw binary data
- Uint8Array: Typed array of bytes
- Buffer: Node.js Buffer (in Node.js environment)
- ReadableStream: Stream of binary data

Age Key Discovery

sops-age automatically discovers age keys using the same logic as SOPS itself. When no secretKey is explicitly provided, the library will search for keys in the following order:

$3

The library can automatically convert SSH private keys to age format:

- Environment variable: SOPS_AGE_SSH_PRIVATE_KEY_FILE - path to SSH private key
- Default locations: ~/.ssh/id_ed25519 and ~/.ssh/id_rsa (in that order)
- Supported types: Ed25519 and RSA keys

`js
// Set environment variable to use specific SSH key
process.env.SOPS_AGE_SSH_PRIVATE_KEY_FILE = "/path/to/my/ssh/key";

// Keys will be auto-discovered and converted
const config = await decryptSops({ path: "./config.enc.json" });
`

$3

- SOPS_AGE_KEY: Direct age private key
- SOPS_AGE_KEY_FILE: Path to file containing age keys
- SOPS_AGE_KEY_CMD: Command that outputs age keys

`js
// Direct key
process.env.SOPS_AGE_KEY = "AGE-SECRET-KEY-1qgdy...";

// Key file
process.env.SOPS_AGE_KEY_FILE = "/path/to/keys.txt";

// Command that outputs keys
process.env.SOPS_AGE_KEY_CMD = "my-key-manager get-age-key";
`

$3

The library checks for age keys in the default SOPS config directory:

- Linux/Unix: ~/.config/sops/age/keys.txt (or $XDG_CONFIG_HOME/sops/age/keys.txt)
- macOS: ~/Library/Application Support/sops/age/keys.txt (or $XDG_CONFIG_HOME/sops/age/keys.txt if set)
- Windows: %APPDATA%\sops\age\keys.txt

Example keys.txt file:

`text


Created: 2024-01-15T10:30:00Z

Public key: age1je6kjhzuhdjy3fqptpttxjh5k8q46vygzlgtpuq3030c947pc5tqz9dqvr

AGE-SECRET-KEY-1QGDY7NWZDM5HG2QMSKQHQZPQF2QJLTQHQZPQF2QJLTQHQZPQF2QJLTQHQZ

Another key

AGE-SECRET-KEY-1ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOP
`

Key Discovery Priority

When no explicit secretKey is provided, keys are discovered in this order:

1. SSH Keys: SOPS_AGE_SSH_PRIVATE_KEY_FILE → ~/.ssh/id_ed25519 → ~/.ssh/id_rsa
2. Age Keys: SOPS_AGE_KEY → SOPS_AGE_KEY_FILE → SOPS_AGE_KEY_CMD
3. Default Config: Platform-specific sops/age/keys.txt file

The library will try all discovered keys until one successfully decrypts the file.

Age Key Utilities

The library includes utilities for discovering age keys and converting SSH keys to age format:

`js
import { sshKeyToAge, sshKeyFileToAge, findAllAgeKeys } from "sops-age";

// Convert SSH key content to age format
const sshKeyContent = "-----BEGIN OPENSSH PRIVATE KEY-----\n...";
const ageKey = sshKeyToAge(sshKeyContent);

// Convert SSH key file to age format
const ageKey = await sshKeyFileToAge("/path/to/ssh/key");

// Discover all available age keys
const allKeys = await findAllAgeKeys();
console.log("Found keys:", allKeys);
`

API Reference

$3

Decrypts SOPS-encrypted content directly from a string, Buffer, or other supported input types.

`js
// With auto-discovered keys
const decrypted = await decryptSops(jsonString, {
fileType: "json",
});

// With explicit key
const decrypted = await decryptSops(jsonString, {
secretKey: "AGE-SECRET-KEY-1qgdy...",
fileType: "json",
});
`

$3

Decrypts a SOPS-encrypted file from the local filesystem.

`js
const decrypted = await decryptSops({
path: "/path/to/config.enc.json",
// secretKey optional - will auto-discover
});
`

$3

Decrypts a SOPS-encrypted file from a URL.

`js
const decrypted = await decryptSops({
url: "https://example.com/config.enc.json",
secretKey: "AGE-SECRET-KEY-1qgdy...", // or auto-discover
});
`

$3

Decrypts SOPS-encrypted content directly from a pre-parsed SOPS object.

`js
const sopsObject = {
secret:
"ENC[AES256_GCM,data:trrpgezXug4Dq9T/inwkMA==,iv:glPwxoY2UuHO91vlJRaqYtFkPY1VsWvkJtfkEKZJdns=,tag:v7DbOYl7C5gdQRdW6BVoLw==,type:str]",
sops: {
// ... SOPS metadata
},
};

// Auto-discovers keys from environment/config
const decrypted = await decryptSops(sopsObject);
`

$3

The decryptSops function accepts the following options:

- secretKey: The age secret key for decryption (optional - will auto-discover if not provided)
- fileType: Optional file type ('env', 'json', or 'yaml'). Auto-detected if not specified
- keyPath: Optional path to decrypt only a specific value
- path: Path to local SOPS file (when using file-based decryption)
- url: URL of SOPS file (when using URL-based decryption)

$3

#### findAllAgeKeys()

Discovers all available age keys (including converted SSH keys) using SOPS logic:

`js
import { findAllAgeKeys } from "sops-age";

const keys = await findAllAgeKeys();
console.log("Available age keys:", keys);
`

#### sshKeyToAge(keyContent, filePath)

Converts SSH private key content to age format:

`js
import { sshKeyToAge } from "sops-age";

const sshKey = "-----BEGIN OPENSSH PRIVATE KEY-----\n...";
const ageKey = sshKeyToAge(sshKey, "id_ed25519");
// Returns: "AGE-SECRET-KEY-1..." or null for unsupported keys
`

#### sshKeyFileToAge(filePath)

Converts SSH private key file to age format:

`js
import { sshKeyFileToAge } from "sops-age";

const ageKey = await sshKeyFileToAge("~/.ssh/id_ed25519");
// Returns: "AGE-SECRET-KEY-1..." or null
`

License

sops-age` is released under the MIT License. See the LICENSE file for more details.