@notur/sdk 1.1.2 → 1.1.4

package/README.md

@@ -5,11 +5,11 @@ Notur Extension Developer SDK. This package provides the runtime helpers and Rea
 ## Install
 
 ```bash
+# Using npm, yarn, pnpm, or bun
 npm install @notur/sdk
-```
-
-```bash
-bun add @notur/sdk
+# or: yarn add @notur/sdk
+# or: pnpm add @notur/sdk
+# or: bun add @notur/sdk
 ```
 
 Peer dependencies:
@@ -70,12 +70,9 @@ All hooks are exported from `@notur/sdk`.
 The SDK includes a CLI tool to package your extension into a `.notur` archive that can be uploaded to the Pterodactyl admin panel.
 
 ```bash
-# From your extension directory
+# From your extension directory (using npx, yarn dlx, pnpm dlx, or bunx)
 npx notur-pack
 
-# Or with bun
-bunx notur-pack
-
 # Specify a different path
 npx notur-pack /path/to/my-extension
 
@@ -89,13 +86,41 @@ This creates a `.notur` file (tar.gz archive) containing:
 
 Upload the resulting `.notur` file to your Pterodactyl admin panel at `/admin/notur/extensions`.
 
-## Build
+## Signing Extensions
+
+The SDK provides tools for Ed25519 signing of extension archives, compatible with the PHP `notur:keygen` and `notur:export --sign` commands.
+
+### Generating a Keypair
 
 ```bash
-bun run build
+npx notur-keygen
 ```
 
+This generates a new Ed25519 keypair and outputs:
+- **Public Key** (64 hex characters) -- Share with panel administrators
+- **Secret Key** (128 hex characters) -- Keep private, used for signing
+
+### Signing an Archive
+
+```bash
+# Using environment variable
+NOTUR_SECRET_KEY=your_secret_key npx notur-pack --sign
+
+# Or with --secret-key flag
+npx notur-pack --sign --secret-key your_secret_key
+```
+
+This produces three files:
+- `vendor-name-1.0.0.notur` -- The extension archive
+- `vendor-name-1.0.0.notur.sha256` -- SHA-256 checksum
+- `vendor-name-1.0.0.notur.sig` -- Ed25519 signature (hex-encoded)
+
+The `.sig` file format is compatible with PHP's `SignatureVerifier::verify()` and panels with `require_signatures` enabled.
+
+## Build
+
 ```bash
+# Using npm, yarn, pnpm, or bun
 npm run build
 ```
 

package/bin/notur-keygen.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * notur-keygen - Generate Ed25519 keypair for signing Notur extensions
+ *
+ * Usage:
+ *   npx notur-keygen
+ *   bunx notur-keygen
+ *
+ * Generates a new Ed25519 keypair and outputs both keys in hex format.
+ * The output format matches the PHP `php artisan notur:keygen` command.
+ */
+
+const sodium = require('libsodium-wrappers');
+
+async function main() {
+    await sodium.ready;
+
+    const keypair = sodium.crypto_sign_keypair();
+
+    const publicKeyHex = sodium.to_hex(keypair.publicKey);
+    const secretKeyHex = sodium.to_hex(keypair.privateKey);
+
+    console.log('Ed25519 keypair generated successfully.');
+    console.log('');
+    console.log('Public Key:');
+    console.log(publicKeyHex);
+    console.log('');
+    console.log('Secret Key:');
+    console.log(secretKeyHex);
+    console.log('');
+    console.log('Store the secret key securely. It is used to sign extension archives.');
+    console.log('Add the public key to your panel configuration:');
+    console.log('');
+    console.log(`  NOTUR_PUBLIC_KEY=${publicKeyHex}`);
+    console.log('');
+    console.log('To sign an archive, set the secret key as an environment variable:');
+    console.log('');
+    console.log(`  NOTUR_SECRET_KEY=${secretKeyHex}`);
+    console.log('  npx notur-pack --sign');
+}
+
+main().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+});

package/bin/notur-pack.js

@@ -6,6 +6,8 @@
  * Usage:
  *   npx notur-pack [path]           # Pack extension at path (default: current dir)
  *   npx notur-pack --output foo.notur
+ *   npx notur-pack --sign           # Sign using NOTUR_SECRET_KEY env var
+ *   npx notur-pack --sign --secret-key xxx
  *   bunx notur-pack
  *
  * A .notur file is a tar.gz archive containing:
@@ -34,11 +36,17 @@ function parseArgs() {
     const options = {
         path: '.',
         output: null,
+        sign: false,
+        secretKey: null,
     };
 
     for (let i = 0; i < args.length; i++) {
         if (args[i] === '--output' || args[i] === '-o') {
             options.output = args[++i];
+        } else if (args[i] === '--sign' || args[i] === '-s') {
+            options.sign = true;
+        } else if (args[i] === '--secret-key') {
+            options.secretKey = args[++i];
         } else if (!args[i].startsWith('-')) {
             options.path = args[i];
         }
@@ -123,7 +131,45 @@ function computeChecksums(dir, files) {
     return checksums;
 }
 
-function pack(sourceDir, outputPath) {
+async function signArchive(archivePath, secretKeyHex) {
+    const sodium = require('libsodium-wrappers');
+    await sodium.ready;
+
+    const content = fs.readFileSync(archivePath);
+    const secretKey = sodium.from_hex(secretKeyHex);
+    const signature = sodium.crypto_sign_detached(content, secretKey);
+
+    return sodium.to_hex(signature);
+}
+
+function getSecretKey(options) {
+    // Check --secret-key argument first, then environment variable
+    const secretKey = options.secretKey || process.env.NOTUR_SECRET_KEY;
+
+    if (!secretKey) {
+        console.error('Error: --sign requires a secret key.');
+        console.error('');
+        console.error('Provide it via:');
+        console.error('  NOTUR_SECRET_KEY=xxx npx notur-pack --sign');
+        console.error('  npx notur-pack --sign --secret-key xxx');
+        console.error('');
+        console.error('Generate a keypair with: npx notur-keygen');
+        process.exit(1);
+    }
+
+    // Validate format: Ed25519 secret keys are 64 bytes = 128 hex chars
+    if (!/^[0-9a-fA-F]{128}$/.test(secretKey)) {
+        console.error('Error: Invalid secret key format.');
+        console.error('Expected 128 hexadecimal characters (64 bytes).');
+        console.error('');
+        console.error('Generate a valid keypair with: npx notur-keygen');
+        process.exit(1);
+    }
+
+    return secretKey;
+}
+
+async function pack(sourceDir, outputPath, options = {}) {
     const resolvedDir = path.resolve(sourceDir);
 
     if (!fs.existsSync(resolvedDir)) {
@@ -174,6 +220,16 @@ function pack(sourceDir, outputPath) {
 
         console.log(`\nCreated: ${outputFullPath}`);
         console.log(`Checksum: ${archiveChecksum}`);
+
+        // Sign the archive if requested
+        if (options.sign) {
+            const secretKey = getSecretKey(options);
+            const signature = await signArchive(outputFullPath, secretKey);
+            const sigPath = outputFullPath + '.sig';
+            fs.writeFileSync(sigPath, signature + '\n');
+            console.log(`Signature: ${sigPath}`);
+        }
+
         console.log(`\nUpload this file to your Pterodactyl admin panel at /admin/notur/extensions`);
 
     } finally {
@@ -186,4 +242,7 @@ function pack(sourceDir, outputPath) {
 
 // Main
 const options = parseArgs();
-pack(options.path, options.output);
+pack(options.path, options.output, options).catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notur/sdk",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Notur Extension Developer SDK",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -15,7 +15,8 @@
     "access": "public"
   },
   "bin": {
-    "notur-pack": "./bin/notur-pack.js"
+    "notur-pack": "./bin/notur-pack.js",
+    "notur-keygen": "./bin/notur-keygen.js"
   },
   "keywords": [
     "notur",
@@ -40,6 +41,7 @@
     "react-dom": "^16.14.0"
   },
   "dependencies": {
+    "libsodium-wrappers": "^0.7.13",
     "yaml": "^2.3.0"
   },
   "devDependencies": {