script-runner-kit 0.1.0 → 0.1.1

package/README.md

@@ -58,12 +58,18 @@ Example `script-runner.config.json`:
 {
   "port": 8088,
   "auditDir": ".script-audit-logs",
-  "authTokens": ["global-secret-a", "global-secret-b"],
+  "akSk": [
+    { "ak": "global-bot-v2", "sk": "global-secret-a" },
+    { "ak": "global-bot-v1", "sk": "global-secret-b" }
+  ],
   "scripts": {
     "check-update": {
       "scriptPath": "./scripts/check-update.sh",
       "rootDir": ".",
-      "authTokens": ["check-secret-a", "check-secret-b"]
+      "akSk": [
+        { "ak": "check-bot-v2", "sk": "check-secret-a" },
+        { "ak": "check-bot-v1", "sk": "check-secret-b" }
+      ]
     }
   }
 }
@@ -75,7 +81,7 @@ Notes:
 - Each script supports either:
   - `scriptPath` (execute via `bash <scriptPath>`)
   - or `command` + optional `args`.
-- Auth uses JWT and supports multiple secrets per script via `authTokens`.
+- Auth uses JWT and supports AK/SK pairs per script via `akSk`.
 
 ### Auto package.json scripts
 
@@ -94,11 +100,18 @@ Every API call requires a JWT token. Supported token sources:
 - `x-runner-token: <token>`
 - query parameter `?token=<token>` (convenient for EventSource demos)
 
+Generate your JWT at `https://jwt.io` using:
+
+- Header: `{"alg":"HS256","typ":"JWT"}`
+- Payload example: `{"sub":"gitai","ak":"check-bot-v2","script":"check-update"}`
+- Secret: use the SK mapped to that AK in your config
+
 Verification rules:
 
 - Uses `jsonwebtoken.verify()` with algorithms `HS256/HS384/HS512`
-- Supports multiple secrets per script (`authTokens` array), useful for key rotation
-- If a script has no local `authTokens`, top-level `authTokens` is used as fallback
+- Supports multiple credentials per script (`akSk` array), useful for key rotation
+- If a script has no local `akSk`, top-level `akSk` is used as fallback
+- Legacy `authTokens` is still accepted for backward compatibility
 
 ## HTTP API
 

package/docs/AUTHENTICATION.md

@@ -10,16 +10,22 @@ Supported sources (priority order):
 2. `x-runner-token: <token>`
 3. Query param `?token=<token>`
 
-## Config example
+## Config example (AK/SK)
 
 ```json
 {
-  "authTokens": ["global-secret-a", "global-secret-b"],
+  "akSk": [
+    { "ak": "global-bot-v2", "sk": "global-secret-a" },
+    { "ak": "global-bot-v1", "sk": "global-secret-b" }
+  ],
   "scripts": {
     "deploy": {
       "command": "npm",
       "args": ["run", "deploy"],
-      "authTokens": ["deploy-secret-v2", "deploy-secret-v1"]
+      "akSk": [
+        { "ak": "deploy-bot-v2", "sk": "deploy-secret-v2" },
+        { "ak": "deploy-bot-v1", "sk": "deploy-secret-v1" }
+      ]
     },
     "build": {
       "command": "npm",
@@ -29,15 +35,58 @@ Supported sources (priority order):
 }
 ```
 
-- Script-level `authTokens` are preferred.
-- If missing, top-level `authTokens` is used.
+- Script-level `akSk` are preferred.
+- If missing, top-level `akSk` is used.
+
+> Backward compatibility: legacy `authTokens` (string array) is still supported.
 
 ## Key rotation
 
-Use multiple secrets and keep new secret first:
+Use multiple AK/SK pairs and keep new credential first:
 
 ```json
-"authTokens": ["new-secret", "old-secret"]
+"akSk": [
+  { "ak": "deploy-bot-v3", "sk": "new-secret" },
+  { "ak": "deploy-bot-v2", "sk": "old-secret" }
+]
 ```
 
-The runner tries each secret until verification succeeds.
+The runner tries matching AK first (from JWT claim `ak`), then falls back to all SKs.
+
+## Generate token (jwt.io)
+
+Use `https://jwt.io` and sign with HS256.
+
+- Header:
+
+```json
+{ "alg": "HS256", "typ": "JWT" }
+```
+
+- Payload example:
+
+```json
+{ "sub": "gitai", "ak": "deploy-bot-v2", "script": "deploy" }
+```
+
+### Payload fields (recommended)
+
+- `sub` (string): caller identity, for audit display (for example `gitai`)
+- `ak` (string): AK name from your `akSk` config (for example `deploy-bot-v2`)
+- `script` (string): target script name (for example `deploy`)
+- `exp` (number, optional): UNIX timestamp expiration (or set via jwt.io expiration UI)
+
+Example payload with expiration:
+
+```json
+{
+  "sub": "gitai",
+  "ak": "deploy-bot-v2",
+  "script": "deploy",
+  "exp": 1893456000
+}
+```
+
+- Secret: use the SK corresponding to `deploy-bot-v2` in your `akSk` config.
+
+Then send the generated JWT via `Authorization: Bearer <token>` (or `x-runner-token` / `?token=`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "script-runner-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Run project scripts via webhook-friendly HTTP endpoints",
   "license": "MIT",
   "type": "commonjs",

package/script-runner.config.json

@@ -1,9 +1,15 @@
 {
   "port": 8088,
   "auditDir": ".script-audit-logs",
-  "authTokens": [
-    "replace-with-strong-jwt-secret-1",
-    "replace-with-strong-jwt-secret-2"
+  "akSk": [
+    {
+      "ak": "global-bot-v2",
+      "sk": "replace-with-strong-jwt-secret-1"
+    },
+    {
+      "ak": "global-bot-v1",
+      "sk": "replace-with-strong-jwt-secret-2"
+    }
   ],
   "scripts": {
     "check-update": {

package/src/config.js

@@ -97,7 +97,7 @@ function loadJsConfig(configPath) {
   return loaded;
 }
 
-function normalizeAuthTokens(value, fieldPath) {
+function normalizeLegacyAuthTokens(value, fieldPath) {
   if (!Array.isArray(value)) {
     throw new Error(`${fieldPath} must be an array of strings`);
   }
@@ -105,7 +105,41 @@ function normalizeAuthTokens(value, fieldPath) {
   if (tokens.length === 0) {
     throw new Error(`${fieldPath} must contain at least one non-empty token`);
   }
-  return tokens;
+  return tokens.map((sk, index) => ({ ak: `legacy-${index + 1}`, sk }));
+}
+
+function normalizeAkSk(value, fieldPath) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${fieldPath} must be an array of { ak, sk } objects`);
+  }
+
+  const entries = value.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`${fieldPath}[${index}] must be an object with ak and sk`);
+    }
+    const ak = String(item.ak || "").trim();
+    const sk = String(item.sk || "").trim();
+    if (!ak || !sk) {
+      throw new Error(`${fieldPath}[${index}] must provide non-empty ak and sk`);
+    }
+    return { ak, sk };
+  });
+
+  if (entries.length === 0) {
+    throw new Error(`${fieldPath} must contain at least one credential`);
+  }
+
+  return entries;
+}
+
+function readAkSkField(source, akSkFieldPath, legacyFieldPath) {
+  if (source.akSk !== undefined) {
+    return normalizeAkSk(source.akSk, akSkFieldPath);
+  }
+  if (source.authTokens !== undefined) {
+    return normalizeLegacyAuthTokens(source.authTokens, legacyFieldPath);
+  }
+  return undefined;
 }
 
 function normalizeScriptFromConfig(configDir, scriptName, scriptConfig) {
@@ -119,16 +153,17 @@ function normalizeScriptFromConfig(configDir, scriptName, scriptConfig) {
       ? scriptConfig.rootDir
       : "."
   );
-  const authTokens =
-    scriptConfig.authTokens === undefined
-      ? undefined
-      : normalizeAuthTokens(scriptConfig.authTokens, `scripts.${scriptName}.authTokens`);
+  const akSk = readAkSkField(
+    scriptConfig,
+    `scripts.${scriptName}.akSk`,
+    `scripts.${scriptName}.authTokens`
+  );
 
   if (typeof scriptConfig.scriptPath === "string" && scriptConfig.scriptPath.trim()) {
     return {
       rootDir: resolvedRootDir,
       scriptPath: path.resolve(configDir, scriptConfig.scriptPath),
-      authTokens,
+      akSk,
     };
   }
 
@@ -146,7 +181,7 @@ function normalizeScriptFromConfig(configDir, scriptName, scriptConfig) {
       rootDir: resolvedRootDir,
       command: scriptConfig.command,
       args,
-      authTokens,
+      akSk,
     };
   }
 
@@ -200,10 +235,7 @@ function resolveScriptConfig(configPath, rawConfig, cwd) {
   }
 
   const configDir = path.dirname(configPath);
-  const globalAuthTokens =
-    rawConfig.authTokens === undefined
-      ? undefined
-      : normalizeAuthTokens(rawConfig.authTokens, "authTokens");
+  const globalAkSk = readAkSkField(rawConfig, "akSk", "authTokens");
   const scripts = rawConfig.scripts || {};
   if (typeof scripts !== "object" || Array.isArray(scripts)) {
     throw new Error("Config field 'scripts' must be an object when provided");
@@ -232,15 +264,15 @@ function resolveScriptConfig(configPath, rawConfig, cwd) {
   }
 
   for (const [scriptName, scriptConfig] of Object.entries(resolvedScripts)) {
-    if (!Array.isArray(scriptConfig.authTokens) || scriptConfig.authTokens.length === 0) {
-      if (globalAuthTokens && globalAuthTokens.length > 0) {
+    if (!Array.isArray(scriptConfig.akSk) || scriptConfig.akSk.length === 0) {
+      if (globalAkSk && globalAkSk.length > 0) {
         resolvedScripts[scriptName] = {
           ...scriptConfig,
-          authTokens: globalAuthTokens,
+          akSk: globalAkSk,
         };
       } else {
         throw new Error(
-          `Auth required for scripts.${scriptName}. Add scripts.${scriptName}.authTokens or top-level authTokens`
+          `Auth required for scripts.${scriptName}. Add scripts.${scriptName}.akSk (or legacy authTokens) or top-level akSk`
         );
       }
     }

package/src/server.js

@@ -51,13 +51,24 @@ function readTokenFromRequest(req, url) {
   return "";
 }
 
-function verifyJwtWithSecrets(token, secrets) {
-  for (const secret of secrets) {
+function verifyJwtWithAkSk(token, akSkList) {
+  const decoded = jwt.decode(token);
+  const hintedAk =
+    decoded && typeof decoded === "object" && typeof decoded.ak === "string"
+      ? decoded.ak.trim()
+      : "";
+
+  const preferred = hintedAk
+    ? akSkList.filter((entry) => entry.ak === hintedAk)
+    : [];
+  const candidates = preferred.length > 0 ? preferred : akSkList;
+
+  for (const credential of candidates) {
     try {
-      const payload = jwt.verify(token, secret, {
+      const payload = jwt.verify(token, credential.sk, {
         algorithms: ["HS256", "HS384", "HS512"],
       });
-      return { ok: true, payload };
+      return { ok: true, payload, ak: credential.ak };
     } catch (err) {
       continue;
     }
@@ -145,7 +156,16 @@ function renderHome(scripts) {
   <li>Trigger: <code>GET /api/&lt;script-name&gt;</code> (for example <code>/api/check</code>)</li>
   <li>Auto-loads scripts from local <code>package.json</code> (config entries take precedence on name conflicts)</li>
   <li>Auth: send JWT via <code>Authorization: Bearer &lt;token&gt;</code>, <code>x-runner-token</code>, or <code>?token=</code></li>
+  <li>AK/SK mode: generate JWT at <a href="https://jwt.io" target="_blank" rel="noopener noreferrer">jwt.io</a> using your script AK's SK</li>
 </ul>
+<h3>jwt.io payload guide</h3>
+<p>Use HS256 and sign with the SK for your AK. Suggested payload:</p>
+<pre>{
+  "sub": "gitai",
+  "ak": "&lt;your-ak&gt;",
+  "script": "&lt;script-name&gt;",
+  "exp": 1893456000
+}</pre>
 <label>script:</label>
 <select id="name">${options}</select>
 <label>jwt token:</label>
@@ -225,7 +245,7 @@ function createServer({ scripts, auditDir }) {
         return;
       }
 
-      const authResult = verifyJwtWithSecrets(token, scriptConfig.authTokens || []);
+      const authResult = verifyJwtWithAkSk(token, scriptConfig.akSk || []);
       if (!authResult.ok) {
         send(res, 403, "Forbidden: invalid token");
         return;
@@ -323,6 +343,40 @@ function createServer({ scripts, auditDir }) {
 function startServer({ scripts, auditDir, port }) {
   const server = createServer({ scripts, auditDir });
   server.listen(port, () => {
+    const lines = [];
+    lines.push("=== Script Runner Effective Config ===");
+    lines.push(`Port: ${port}`);
+    lines.push(`Audit dir: ${auditDir}`);
+    lines.push(`Scripts: ${Object.keys(scripts).length}`);
+    lines.push("");
+    lines.push("Configured scripts:");
+
+    for (const [scriptName, script] of Object.entries(scripts)) {
+      const runTarget = script.scriptPath
+        ? `bash ${script.scriptPath}`
+        : `${script.command || ""} ${Array.isArray(script.args) ? script.args.join(" ") : ""}`.trim();
+      lines.push(`- ${scriptName}`);
+      lines.push(`  rootDir : ${script.rootDir}`);
+      lines.push(`  run     : ${runTarget}`);
+
+      if (Array.isArray(script.akSk) && script.akSk.length > 0) {
+        lines.push("  secrets :");
+        for (const item of script.akSk) {
+          lines.push(`    - ${item.ak} => ${item.sk}`);
+        }
+      } else {
+        lines.push("  secrets : (none)");
+      }
+    }
+
+    lines.push("");
+    lines.push("JWT generation (recommended): https://jwt.io");
+    lines.push("Header : {\"alg\":\"HS256\",\"typ\":\"JWT\"}");
+    lines.push("Payload: {\"sub\":\"<user>\",\"ak\":\"<ak>\",\"script\":\"<script-name>\"}");
+    lines.push("Secret : use the SK mapped to that AK in your config");
+    lines.push("======================================");
+
+    process.stdout.write(`${lines.join("\n")}\n`);
     process.stdout.write(`Server listening on http://0.0.0.0:${port}\n`);
   });
   return server;