self-sign 5.6.7

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(npm test)",
+      "Bash(gh issue view:*)",
+      "Bash(npx mocha:*)",
+      "Bash(gh issue comment:*)",
+      "Bash(gh issue close:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.github/workflows/pr-tests.yml

@@ -0,0 +1,27 @@
+name: PR Tests
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [18.x, 20.x, 22.x, 24.x]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/.jshintrc

@@ -0,0 +1,39 @@
+{
+  "camelcase": false,
+  "curly": false,
+
+  "node": true,
+  "esnext": true,
+  "bitwise": true,
+  "eqeqeq": true,
+  "immed": true,
+  "indent": 2,
+  "latedef": true,
+  "newcap": true,
+  "noarg": true,
+  "regexp": true,
+  "undef": true,
+  "strict": false,
+  "smarttabs": true,
+  "expr": true,
+
+  "evil": true,
+  "browser": true,
+  "regexdash": true,
+  "wsh": true,
+  "trailing": true,
+  "sub": true,
+  "unused": true,
+  "laxcomma": true,
+
+  "globals": {
+    "after": false,
+    "before": false,
+    "afterEach": false,
+    "beforeEach": false,
+    "describe": false,
+    "it": false,
+    "DOMParser": true,
+    "XMLSerializer": true
+  }
+}

package/.nvmrc

@@ -0,0 +1 @@
+22

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.0] - 2025-11-26
+
+### 🚀 Major Rewrite
+
+Complete rewrite replacing `node-forge` with modern `@peculiar/x509` and `pkijs` libraries.
+
+### ✨ Added
+
+- Native WebCrypto API support for better performance and security
+- TypeScript examples in documentation
+- Async/await support as the primary API
+- Support for `keyPair` option to use existing keys
+- Updated to use Node.js native crypto for all operations
+- Separate `selfsign/pkcs7` module for tree-shakeable PKCS#7 support
+
+### 💥 BREAKING CHANGES
+
+1. **Async-only API**: The `generate()` function now returns a Promise. Synchronous generation has been removed.
+   ```js
+   // Old (v4.x)
+   const pems = selfsign.generate(attrs, options);
+
+   // New (v5.x)
+   const pems = await selfsign.generate(attrs, options);
+   ```
+
+2. **No callback support**: Callbacks have been completely removed in favor of Promises.
+   ```js
+   // Old (v4.x)
+   selfsign.generate(attrs, options, function(err, pems) { ... });
+
+   // New (v5.x)
+   const pems = await selfsign.generate(attrs, options);
+   ```
+
+3. **Minimum Node.js version**: Now requires Node.js >= 15.6.0 (was >= 10)
+   - Required for native WebCrypto support
+
+4. **Dependencies changed**:
+   - ❌ Removed: `node-forge` (1.64 MB)
+   - ✅ Added: `@peculiar/x509` (551 KB) - 66% smaller!
+   - ✅ Added: `pkijs` (1.94 MB, only for PKCS#7 support)
+   - Bundle size reduced by 66% when not using PKCS#7
+
+5. **PKCS#7 API changed**:
+   - Old: `const pems = await generate(attrs, { pkcs7: true }); pems.pkcs7`
+   - New: `const { createPkcs7 } = require('selfsign/pkcs7'); const pkcs7 = createPkcs7(pems.cert);`
+   - PKCS#7 is now a separate module for better tree-shaking
+
+### 🔧 Changed
+
+- Default key size remains 2048 bits (was incorrectly documented as 1024)
+- PEM output uses `\n` line endings (was `\r\n`)
+- Private keys now use PKCS#8 format (`BEGIN PRIVATE KEY` instead of `BEGIN RSA PRIVATE KEY`)
+- Certificate generation is now fully async using native WebCrypto
+- **PKCS#7 is now tree-shakeable**: Moved to separate `selfsign/pkcs7` module so bundlers can exclude it when not used
+
+### 🐛 Fixed
+
+- Default key size documentation corrected from 1024 to 2048 bits
+- Improved error handling for certificate generation failures
+
+### 📦 Dependencies
+
+**Removed:**
+- `node-forge@^1.3.1`
+- `@types/node-forge@^1.3.0`
+
+**Added:**
+- `@peculiar/x509@^1.14.2` (required)
+- `pkijs@^3.3.3` (required, but tree-shakeable via separate `selfsign/pkcs7` module)
+
+### 🔒 Security
+
+- Now uses Node.js native WebCrypto API instead of JavaScript implementation
+- Better integration with platform security features
+- More secure random number generation
+
+### 📚 Documentation
+
+- Complete README rewrite with async/await examples
+- Added migration guide from v4.x to v5.x
+- Updated all code examples to use async/await
+- Added requirements section highlighting Node.js version requirement
+
+---
+
+## [4.0.0] - Previous Release
+
+See git history for changes in 4.x and earlier versions.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2013 José F. Romaniello
+
+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,474 @@
+# selfsign
+
+Generate self-sign X.509 certificates using Node.js native crypto.
+
+## Install
+
+```bash
+npm install selfsign
+```
+
+## Requirements
+
+- **Node.js >= 15.6.0** (for native WebCrypto support)
+
+## Usage
+
+**Version 5.0 is async-only.** The `generate()` function now returns a Promise.
+
+```js
+const selfsign = require('self-sign');
+
+const attrs = [{ name: 'commonName', value: 'contoso.com' }];
+const pems = await selfsign.generate(attrs);
+console.log(pems);
+```
+
+### Output
+
+```js
+{
+  private: '-----BEGIN PRIVATE KEY-----\n...',
+  public: '-----BEGIN PUBLIC KEY-----\n...',
+  cert: '-----BEGIN CERTIFICATE-----\n...',
+  fingerprint: 'XX:XX:XX:...'
+}
+```
+
+## Options
+
+```js
+const pems = await selfsign.generate(null, {
+  keyType: 'rsa', // key type: 'rsa' or 'ec' (default: 'rsa')
+  keySize: 2048, // the size for the private key in bits (default: 2048, RSA only)
+  curve: 'P-256', // elliptic curve: 'P-256', 'P-384', or 'P-521' (default: 'P-256', EC only)
+  notBeforeDate: new Date(), // start of certificate validity (default: now)
+  notAfterDate: new Date('2026-01-01'), // end of certificate validity (default: notBeforeDate + 365 days)
+  algorithm: 'sha256', // sign the certificate with specified algorithm (default: 'sha1')
+  extensions: [{ name: 'basicConstraints', cA: true }], // certificate extensions array
+  clientCertificate: true, // generate client cert (default: false) - can also be an options object
+  ca: { key: '...', cert: '...' }, // CA key and cert for signing (default: self-sign)
+  passphrase: 'secret' // encrypt the private key with a passphrase (default: none)
+},null);
+```
+
+### Setting Custom Validity Period
+
+Use `notBeforeDate` and `notAfterDate` to control certificate validity:
+
+```js
+// Using date-fns
+const { addDays, addYears } = require('date-fns');
+
+const pems = await selfsign.generate(null, {
+  notBeforeDate: new Date(),
+  notAfterDate: addDays(new Date(), 30) // Valid for 30 days
+},null);
+
+// Or with vanilla JS
+const notBefore = new Date();
+const notAfter = new Date(notBefore);
+notAfter.setFullYear(notAfter.getFullYear() + 2); // Valid for 2 years
+
+const pems = await selfsign.generate(null, {
+  notBeforeDate: notBefore,
+  notAfterDate: notAfter
+},null);
+```
+
+### Supported Algorithms
+
+- `sha1` (default)
+- `sha256`
+- `sha384`
+- `sha512`
+
+### Custom Extensions
+
+You can customize certificate extensions using the `extensions` option. This is useful for adding Subject Alternative Names (SANs) with IPv6 addresses, custom key usage, and more.
+
+```js
+const pems = await selfsign.generate(
+  [{ name: 'commonName', value: 'localhost' }],
+  {
+    extensions: [
+      {
+        name: 'basicConstraints',
+        cA: false
+      },
+      {
+        name: 'keyUsage',
+        digitalSignature: true,
+        keyEncipherment: true
+      },
+      {
+        name: 'subjectAltName',
+        altNames: [
+          { type: 2, value: 'localhost' },     // DNS
+          { type: 7, ip: '127.0.0.1' },        // IPv4
+          { type: 7, ip: '::1' }               // IPv6
+        ]
+      }
+    ]
+  },null
+);
+```
+
+#### Supported Extensions
+
+**basicConstraints**
+```js
+{
+  name: 'basicConstraints',
+  cA: true,                    // is this a CA certificate?
+  pathLenConstraint: 0,        // max depth of valid cert chain (optional)
+  critical: true               // mark as critical extension
+}
+```
+
+**keyUsage**
+```js
+{
+  name: 'keyUsage',
+  digitalSignature: true,
+  nonRepudiation: true,
+  keyEncipherment: true,
+  dataEncipherment: true,
+  keyAgreement: true,
+  keyCertSign: true,          // for CA certificates
+  cRLSign: true,              // for CA certificates
+  encipherOnly: true,
+  decipherOnly: true,
+  critical: true
+}
+```
+
+**extKeyUsage** (Extended Key Usage)
+```js
+{
+  name: 'extKeyUsage',
+  serverAuth: true,           // TLS server authentication
+  clientAuth: true,           // TLS client authentication
+  codeSigning: true,
+  emailProtection: true,
+  timeStamping: true
+}
+```
+
+**subjectAltName** (Subject Alternative Name)
+```js
+{
+  name: 'subjectAltName',
+  altNames: [
+    { type: 1, value: 'user@example.com' },           // email (rfc822Name)
+    { type: 2, value: 'example.com' },                // DNS name
+    { type: 2, value: '*.example.com' },              // wildcard DNS
+    { type: 6, value: 'http://example.com/webid' },   // URI
+    { type: 7, ip: '127.0.0.1' },                     // IPv4 address
+    { type: 7, ip: '::1' }                            // IPv6 address
+  ]
+}
+```
+
+#### Default Extensions
+
+When no `extensions` option is provided (or an empty array), the following defaults are used:
+
+```js
+[
+  { name: 'basicConstraints', cA: false, critical: true },
+  { name: 'keyUsage', digitalSignature: true, keyEncipherment: true, critical: true },
+  { name: 'extKeyUsage', serverAuth: true, clientAuth: true },
+  { name: 'subjectAltName', altNames: [
+    { type: 2, value: commonName },
+    // For localhost, also includes: { type: 7, ip: '127.0.0.1' }
+  ]}
+]
+```
+
+### Elliptic Curve (EC) Keys
+
+By default, selfsign generates RSA keys. You can generate certificates using elliptic curve cryptography instead, which provides equivalent security with smaller key sizes and faster operations.
+
+```js
+// Generate EC certificate with P-256 curve (default)
+const pems = await selfsign.generate(null, { keyType: 'ec' },null);
+
+// Generate EC certificate with P-384 curve
+const pems = await selfsign.generate(null, { keyType: 'ec', curve: 'P-384' },null);
+
+// Generate EC certificate with P-521 curve and SHA-512
+const pems = await selfsign.generate(null, {
+  keyType: 'ec',
+  curve: 'P-521',
+  algorithm: 'sha512'
+},null);
+```
+
+**Supported curves:**
+- `P-256` (default) - 128-bit security, fastest
+- `P-384` - 192-bit security
+- `P-521` - 256-bit security, strongest
+
+EC keys work with all other options including `clientCertificate`, `passphrase`, `ca`, and `keyPair`:
+
+```js
+// EC certificate with encrypted private key
+const pems = await selfsign.generate(null, {
+  keyType: 'ec',
+  passphrase: 'secret'
+},null);
+
+// EC certificate with client certificate
+const pems = await selfsign.generate(null, {
+  keyType: 'ec',
+  clientCertificate: true
+},null);
+
+// Reuse existing EC key pair
+const pems = await selfsign.generate(null, {
+  keyType: 'ec',
+  curve: 'P-256',
+  keyPair: {
+    publicKey: existingPublicKey,
+    privateKey: existingPrivateKey
+  }
+},null);
+```
+
+### Using Your Own Keys
+
+You can avoid key pair generation by specifying your own keys:
+
+```js
+const pems = await selfsign.generate(null, {
+  keyPair: {
+    publicKey: '-----BEGIN PUBLIC KEY-----...',
+    privateKey: '-----BEGIN PRIVATE KEY-----...'
+  }
+},null);
+```
+
+### Encrypting the Private Key
+
+You can encrypt the private key with a passphrase using AES-256-CBC:
+
+```js
+const pems = await selfsign.generate(null, {
+  passphrase: 'my-secret-passphrase'
+},null);
+
+// The private key will be in encrypted PKCS#8 format:
+// -----BEGIN ENCRYPTED PRIVATE KEY-----
+// ...
+// -----END ENCRYPTED PRIVATE KEY-----
+```
+
+To use the encrypted key, provide the passphrase:
+
+```js
+const crypto = require('crypto');
+
+// Decrypt the key
+const privateKey = crypto.createPrivateKey({
+  key: pems.private,
+  passphrase: 'my-secret-passphrase'
+});
+
+// Or use directly with HTTPS server
+const https = require('https');
+https.createServer({
+  key: pems.private,
+  passphrase: 'my-secret-passphrase',
+  cert: pems.cert
+}, app).listen(443);
+```
+
+### Signing with a CA
+
+You can generate certificates signed by an existing Certificate Authority instead of self-sign certificates. This is useful for development environments where you want browsers to trust your certificates.
+
+```js
+const fs = require('fs');
+const selfsign = require('self-sign');
+
+const pems = await selfsign.generate([
+  { name: 'commonName', value: 'localhost' }
+], {
+  algorithm: 'sha256',
+  ca: {
+    key: fs.readFileSync('/path/to/ca.key', 'utf8'),
+    cert: fs.readFileSync('/path/to/ca.crt', 'utf8')
+  }
+},null);
+```
+
+The generated certificate will be signed by the provided CA and will include:
+- Subject Alternative Name (SAN) extension with DNS name matching the commonName
+- For `localhost`, an additional IP SAN for `127.0.0.1`
+- Key Usage: digitalSignature, keyEncipherment
+- Extended Key Usage: serverAuth, clientAuth
+
+#### Using with mkcert
+
+[mkcert](https://github.com/FiloSottile/mkcert) is a simple tool for making locally-trusted development certificates. Combining it with `selfsign` provides an excellent developer experience:
+
+- **No certificate files to manage** - generate trusted certificates on-the-fly at server startup
+- **No git-ignored cert files** - nothing to store, share, or accidentally commit
+- **Browsers trust the certificates automatically** - no security warnings during development
+
+```js
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const selfsign = require('self-sign');
+
+// Get mkcert's CA (requires: brew install mkcert && mkcert -install)
+const caroot = execSync('mkcert -CAROOT', { encoding: 'utf8' }).trim();
+
+const pems = await selfsign.generate([
+  { name: 'commonName', value: 'localhost' }
+], {
+  algorithm: 'sha256',
+  ca: {
+    key: fs.readFileSync(path.join(caroot, 'rootCA-key.pem'), 'utf8'),
+    cert: fs.readFileSync(path.join(caroot, 'rootCA.pem'), 'utf8')
+  }
+},null);
+
+// Start server with browser-trusted certificate - no files written to disk
+https.createServer({ key: pems.private, cert: pems.cert }, app).listen(443);
+```
+
+See [examples/https-server-mkcert.js](examples/https-server-mkcert.js) for a complete working example.
+
+## Attributes
+
+Attributes follow the X.509 standard:
+
+```js
+const attrs = [
+  { name: 'commonName', value: 'example.org' },
+  { name: 'countryName', value: 'US' },
+  { shortName: 'ST', value: 'Virginia' },
+  { name: 'localityName', value: 'Blacksburg' },
+  { name: 'organizationName', value: 'Test' },
+  { shortName: 'OU', value: 'Test' }
+];
+```
+
+## Generate Client Certificates
+
+For environments where servers require client certificates, you can generate client keys signed by the original (server) key:
+
+```js
+const pems = await selfsign.generate(null, { clientCertificate: true },null);
+console.log(pems);
+```
+
+Output includes additional client certificate fields:
+
+```js
+{
+  private: '-----BEGIN PRIVATE KEY-----\n...',
+  public: '-----BEGIN PUBLIC KEY-----\n...',
+  cert: '-----BEGIN CERTIFICATE-----\n...',
+  fingerprint: 'XX:XX:XX:...',
+  clientprivate: '-----BEGIN PRIVATE KEY-----\n...',
+  clientpublic: '-----BEGIN PUBLIC KEY-----\n...',
+  clientcert: '-----BEGIN CERTIFICATE-----\n...'
+}
+```
+
+### Client Certificate Options
+
+The `clientCertificate` option can be `true` for defaults, or an options object for full control:
+
+```js
+const pems = await selfsign.generate(null, {
+  clientCertificate: {
+    cn: 'jdoe',                              // common name (default: 'John Doe jdoe123')
+    keyType: 'rsa',                          // key type: 'rsa' or 'ec' (default: inherits from parent)
+    keySize: 4096,                           // key size in bits (default: 2048, RSA only)
+    curve: 'P-256',                          // elliptic curve (default: 'P-256', EC only)
+    algorithm: 'sha256',                     // signature algorithm (default: inherits from parent or 'sha1')
+    notBeforeDate: new Date(),               // validity start (default: now)
+    notAfterDate: new Date('2026-01-01')     // validity end (default: notBeforeDate + 1 year)
+  }
+},null);
+```
+
+Simple example with just a custom CN:
+
+```js
+const pems = await selfsign.generate(null, {
+  clientCertificate: { cn: 'FooBar' }
+},null);
+```
+
+## PKCS#7 Support
+
+PKCS#7 formatting is available through a separate module for better tree-shaking:
+
+```js
+const selfsign = require('self-sign');
+const { createPkcs7 } = require('self-sign/pkcs7');
+
+const pems = await selfsign.generate(attrs);
+const pkcs7 = createPkcs7(pems.cert);
+console.log(pkcs7); // PKCS#7 formatted certificate
+```
+
+You can also create PKCS#7 for client certificates:
+
+```js
+const pems = await selfsign.generate(null, { clientCertificate: true },null);
+const clientPkcs7 = createPkcs7(pems.clientcert);
+```
+
+## Migration from v4.x
+
+Version 5.0 introduces breaking changes:
+
+### Breaking Changes
+
+1. **Async-only API**: The `generate()` function is now async and returns a Promise. Synchronous generation is no longer supported.
+2. **No callback support**: Callbacks have been removed. Use `async`/`await` or `.then()`.
+3. **Minimum Node.js version**: Now requires Node.js >= 15.6.0 (was >= 10).
+4. **Dependencies**: Replaced `node-forge` with `@peculiar/x509` and `pkijs` (66% smaller bundle size).
+5. **`days` option removed**: Use `notAfterDate` instead. Default validity is 365 days from `notBeforeDate`.
+
+### Migration Examples
+
+**Old (v4.x):**
+```js
+// Sync
+const pems = selfsign.generate(attrs, { days: 365 });
+
+// Callback
+selfsign.generate(attrs, { days: 365 },null, function(err, pems) {
+  if (err) throw err;
+  console.log(pems);
+});
+```
+
+**New (v5.x):**
+```js
+// Async/await (default 365 days validity)
+const pems = await selfsign.generate(attrs);
+
+// Custom validity with notAfterDate
+const notAfter = new Date();
+notAfter.setDate(notAfter.getDate() + 30); // 30 days
+const pems = await selfsign.generate(attrs, { notAfterDate: notAfter });
+
+// Or with .then()
+selfsign.generate(attrs)
+  .then(pems => console.log(pems))
+  .catch(err => console.error(err));
+```
+
+## License
+
+MIT