@fprad0/skill-master-mcp 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -7,6 +7,12 @@ All notable changes to `skill_master` will be tracked here.
 - Prepare a public npm publication path with dedicated workflow and operator guide.
 - Upgrade release automation from Node `20` to Node `22`.
 
+## [0.0.6] - 2026-06-26
+
+- Harden `skill-master-configure-private-registry` with HTTPS registry validation, scoped token handling, redacted dry-runs, timestamped backups, and POSIX `0600` permissions.
+- Store `${GITHUB_PACKAGES_TOKEN}` in `.npmrc` by default instead of persisting a literal token.
+- Add `--token-file`, `--token-stdin`, and explicit `--store-token` support for safer operator workflows.
+
 ## [0.0.5] - 2026-06-26
 
 - Add `skill-master-update` to update the global npm installation safely outside the MCP stdio process.

package/README.md

@@ -81,6 +81,8 @@ Bootstrap direto pelo pacote, para maquinas que ja conseguem resolver o escopo `
 - PowerShell: `$env:GITHUB_PACKAGES_TOKEN='SEU_TOKEN'; npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate`
 - Bash: `GITHUB_PACKAGES_TOKEN='SEU_TOKEN' npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate`
 
+Por padrao, o configurador grava o `.npmrc` usando `${GITHUB_PACKAGES_TOKEN}` em vez de persistir o token literal. Para ambientes que exigem token gravado no arquivo, use `--store-token` de forma consciente.
+
 Exemplo de `.npmrc`:
 
 ```ini

package/VERSION.md

@@ -2,8 +2,8 @@
 
 Versão funcional planejada: `00.02`
 
-Versão técnica para empacotamento semântico: `0.0.5`
+Versão técnica para empacotamento semântico: `0.0.6`
 
 ## Observação
 
-O nome `00.02` será usado na comunicação e nos documentos. Para ferramentas que exigem SemVer, como npm e alguns fluxos de release, usar `0.0.5`.
+O nome `00.02` será usado na comunicação e nos documentos. Para ferramentas que exigem SemVer, como npm e alguns fluxos de release, usar `0.0.6`.

package/docs/operations/GUIA_NPM_PRIVADO.md

@@ -11,6 +11,23 @@ O fluxo usa:
 - execucao via `npx @fprad0/skill-master-mcp`;
 - configuracao MCP por `stdio`.
 
+## Modelo de seguranca do `.npmrc`
+
+O configurador segue tres regras:
+
+- o token fica escopado ao host do registry, por exemplo `//npm.pkg.github.com/:_authToken=...`;
+- o registry precisa usar HTTPS por padrao;
+- o arquivo `.npmrc` usa referencia de variavel de ambiente por padrao, evitando gravar o token literal.
+
+Conteudo recomendado:
+
+```ini
+@fprad0:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Se voce precisar persistir o token literal dentro do `.npmrc`, use `--store-token` de forma consciente. Esse modo e menos seguro, mas pode ser necessario em maquinas sem suporte simples a variaveis de ambiente persistentes.
+
 ## Pre-requisitos
 
 - Node.js e npm instalados;
@@ -65,7 +82,8 @@ O script:
 
 - pede o token de forma segura se ele no estiver em variavel de ambiente;
 - atualiza apenas as linhas necessrias do `%USERPROFILE%\.npmrc`;
-- cria backup em `%USERPROFILE%\.npmrc.bak` se o arquivo j existir;
+- cria backup com timestamp se o arquivo ja existir;
+- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
 - valida acesso ao pacote com `npm view`;
 - mostra o comando final de `npx`.
 
@@ -75,11 +93,17 @@ Crie ou atualize o arquivo:
 %USERPROFILE%\.npmrc
 ```
 
-Com o conteudo:
+Com o conteudo recomendado:
 
 ```ini
 @fprad0:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=SEU_TOKEN_AQUI
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Se preferir gravar o token literal no `.npmrc`:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate -StoreToken
 ```
 
 ### Jeito rapido sem checkout local
@@ -91,6 +115,12 @@ $env:GITHUB_PACKAGES_TOKEN='SEU_TOKEN'
 npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
 ```
 
+Para ler o token de arquivo, evitando argumento em historico de shell:
+
+```powershell
+npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-file .\github-packages-token.txt --validate
+```
+
 ## Validar acesso ao pacote
 
 ```bat
@@ -112,6 +142,8 @@ O script:
 - pede o token sem eco no terminal quando necessario;
 - atualiza apenas as linhas do escopo `@fprad0`;
 - cria ou reaproveita `${HOME}/.npmrc`;
+- aplica permissao `0600` no `${HOME}/.npmrc`;
+- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
 - valida acesso ao pacote;
 - mostra o comando final de `npx`.
 
@@ -123,6 +155,18 @@ Use esta opcao quando a maquina ja consegue resolver o escopo `@fprad0` no GitHu
 GITHUB_PACKAGES_TOKEN='SEU_TOKEN' npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
 ```
 
+Para ler o token via stdin:
+
+```bash
+printf '%s' "$GITHUB_PACKAGES_TOKEN" | npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-stdin --validate
+```
+
+Para gravar token literal no `.npmrc` quando necessario:
+
+```bash
+bash ./scripts/configure-private-registry.sh --validate --store-token
+```
+
 ## Publicacao pelo workflow
 
 O workflow de release usa:

package/manifests/channels/beta.json

@@ -2,12 +2,12 @@
   "name": "skill_master",
   "channel": "beta",
   "version": "00.02-beta",
-  "semver": "0.0.5",
-  "publishedAt": "2026-06-26T14:35:00-03:00",
+  "semver": "0.0.6",
+  "publishedAt": "2026-06-26T16:45:00-03:00",
   "git": {
     "repo": "https://github.com/FPrad0/skill-master-mcp",
     "branch": "main",
-    "commit": "af41244"
+    "commit": "c203ead"
   },
   "node": {
     "minimum": "18.0.0"
@@ -19,7 +19,7 @@
     "buildCommand": "npm run build"
   },
   "changelog": [
-    "Canal beta acompanha o novo comando skill-master-update.",
-    "Update npm fica disponivel via comando separado e pelo menu operacional."
+    "Canal beta acompanha o configurador privado mais seguro.",
+    "Fluxos de token passam a suportar arquivo, stdin e armazenamento literal somente com opt-in."
   ]
 }

package/manifests/channels/stable.json

@@ -2,12 +2,12 @@
   "name": "skill_master",
   "channel": "stable",
   "version": "00.02",
-  "semver": "0.0.5",
-  "publishedAt": "2026-06-26T14:35:00-03:00",
+  "semver": "0.0.6",
+  "publishedAt": "2026-06-26T16:45:00-03:00",
   "git": {
     "repo": "https://github.com/FPrad0/skill-master-mcp",
     "branch": "main",
-    "commit": "af41244"
+    "commit": "c203ead"
   },
   "node": {
     "minimum": "18.0.0"
@@ -19,8 +19,8 @@
     "buildCommand": "npm run build"
   },
   "changelog": [
-    "Novo binario skill-master-update para atualizar instalacao global via npm.",
-    "Menu operacional passa a incluir opcao de update global seguro.",
-    "Fluxo evita atualizar arquivos durante execucao do servidor MCP stdio."
+    "Configurador privado passa a gravar referencia de variavel de ambiente por padrao.",
+    "Validacao de registry HTTPS, backups com timestamp, dry-run redigido e permissao 0600 em POSIX.",
+    "Novas entradas --token-file, --token-stdin e --store-token."
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fprad0/skill-master-mcp",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "private": false,
   "type": "module",
   "description": "Personal MCP server that catalogs, recommends and reports skills with update-aware metadata.",

package/scripts/configure-private-registry.mjs

@@ -1,14 +1,39 @@
 import { spawnSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import {
   DEFAULT_PACKAGE_NAME,
   DEFAULT_REGISTRY_URL,
   DEFAULT_SCOPE,
   DEFAULT_TOKEN_ENV,
+  redactSensitiveNpmrc,
   upsertNpmrc,
 } from './lib/private-registry.mjs';
 
+function printHelp() {
+  process.stdout.write(`Skill Master private registry configurator
+
+Usage:
+  skill-master-configure-private-registry [options]
+
+Options:
+  --npmrc <path>              Target .npmrc path. Defaults to the user .npmrc.
+  --scope <scope>             npm scope. Defaults to @fprad0.
+  --registry <url>            Registry URL. Defaults to https://npm.pkg.github.com.
+  --token <token>             Token for validation. Avoid in shared shell history.
+  --token-file <path>         Read token from a local file.
+  --token-stdin               Read token from stdin.
+  --token-env <name>          Environment variable name. Defaults to GITHUB_PACKAGES_TOKEN.
+  --store-token               Persist the token literal in .npmrc. Default stores \${TOKEN_ENV}.
+  --allow-insecure-registry   Allow http only for localhost/private test registries.
+  --no-backup                 Do not create a timestamped backup.
+  --dry-run                   Print a redacted preview without writing.
+  --validate                  Run npm view after writing.
+  --package <name>            Package used for validation.
+  --help                      Show this help.
+`);
+}
+
 function parseArgs(argv) {
   const parsed = {
     npmrc: resolve(process.env.USERPROFILE ?? process.env.HOME ?? '.', '.npmrc'),
@@ -19,6 +44,9 @@ function parseArgs(argv) {
     dryRun: false,
     validate: false,
     packageName: DEFAULT_PACKAGE_NAME,
+    storeToken: false,
+    allowInsecureRegistry: false,
+    help: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -36,9 +64,21 @@ function parseArgs(argv) {
       case '--token':
         parsed.token = argv[++i];
         break;
+      case '--token-file':
+        parsed.tokenFile = resolve(argv[++i]);
+        break;
+      case '--token-stdin':
+        parsed.tokenStdin = true;
+        break;
       case '--token-env':
         parsed.tokenEnv = argv[++i];
         break;
+      case '--store-token':
+        parsed.storeToken = true;
+        break;
+      case '--allow-insecure-registry':
+        parsed.allowInsecureRegistry = true;
+        break;
       case '--no-backup':
         parsed.backup = false;
         break;
@@ -51,6 +91,10 @@ function parseArgs(argv) {
       case '--package':
         parsed.packageName = argv[++i];
         break;
+      case '--help':
+      case '-h':
+        parsed.help = true;
+        break;
       default:
         throw new Error(`Unknown argument: ${arg}`);
     }
@@ -59,12 +103,39 @@ function parseArgs(argv) {
   return parsed;
 }
 
+function readToken(options) {
+  if (options.token) {
+    return options.token;
+  }
+
+  if (options.tokenFile) {
+    return readFileSync(options.tokenFile, 'utf8').trim();
+  }
+
+  if (options.tokenStdin) {
+    return readFileSync(0, 'utf8').trim();
+  }
+
+  return process.env[options.tokenEnv];
+}
+
+function buildBackupPath(npmrcPath) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `${npmrcPath}.bak.${timestamp}`;
+}
+
 function main() {
   const options = parseArgs(process.argv.slice(2));
-  const token = options.token ?? process.env[options.tokenEnv];
 
-  if (!token) {
-    throw new Error(`Token not provided. Use --token or define ${options.tokenEnv}.`);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const token = readToken(options);
+  const needsToken = options.storeToken || options.validate;
+  if (needsToken && !token) {
+    throw new Error(`Token not provided. Use --token-file, --token-stdin, --token, or define ${options.tokenEnv}.`);
   }
 
   const currentContent = existsSync(options.npmrc)
@@ -75,16 +146,24 @@ function main() {
     scope: options.scope,
     registryUrl: options.registry,
     tokenValue: token,
+    tokenEnv: options.tokenEnv,
+    storeToken: options.storeToken,
+    allowInsecureRegistry: options.allowInsecureRegistry,
   });
 
   const changed = nextContent !== currentContent.replace(/\r\n/g, '\n');
 
-  if (!options.dryRun) {
+  if (options.dryRun) {
+    process.stdout.write(redactSensitiveNpmrc(nextContent));
+  } else {
     mkdirSync(dirname(options.npmrc), { recursive: true });
     if (changed && options.backup && existsSync(options.npmrc)) {
-      copyFileSync(options.npmrc, `${options.npmrc}.bak`);
+      copyFileSync(options.npmrc, buildBackupPath(options.npmrc));
     }
     writeFileSync(options.npmrc, nextContent, 'utf8');
+    if (process.platform !== 'win32') {
+      chmodSync(options.npmrc, 0o600);
+    }
   }
 
   if (options.validate) {
@@ -95,7 +174,11 @@ function main() {
     const result = spawnSync(
       'npm',
       ['view', options.packageName, `--registry=${options.registry}`],
-      { stdio: 'inherit', shell: process.platform === 'win32' },
+      {
+        env: { ...process.env, [options.tokenEnv]: token },
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+      },
     );
 
     if (result.status !== 0) {
@@ -108,6 +191,7 @@ function main() {
       `[skill_master] ${options.dryRun ? 'Preview ready for' : 'Configured'} ${options.npmrc}`,
       `[skill_master] Scope: ${options.scope}`,
       `[skill_master] Registry: ${options.registry}`,
+      `[skill_master] Token storage: ${options.storeToken ? 'literal token in .npmrc' : `environment reference \${${options.tokenEnv}}`}`,
       `[skill_master] Changed: ${changed ? 'yes' : 'no'}`,
       `[skill_master] Validate with: npm view ${options.packageName} --registry=${options.registry}`,
       `[skill_master] Run with: npx -y ${options.packageName}@latest`,

package/scripts/lib/private-registry.mjs

@@ -3,30 +3,68 @@ export const DEFAULT_PACKAGE_NAME = '@fprad0/skill-master-mcp';
 export const DEFAULT_REGISTRY_URL = 'https://npm.pkg.github.com';
 export const DEFAULT_TOKEN_ENV = 'GITHUB_PACKAGES_TOKEN';
 
-export function registryHostFromUrl(registryUrl = DEFAULT_REGISTRY_URL) {
-  return new URL(registryUrl).host;
+export function normalizeRegistryUrl(registryUrl = DEFAULT_REGISTRY_URL, { allowInsecure = false } = {}) {
+  const parsed = new URL(registryUrl);
+  const isLocalhost = ['localhost', '127.0.0.1', '::1'].includes(parsed.hostname);
+
+  if (parsed.protocol !== 'https:' && !(allowInsecure && isLocalhost)) {
+    throw new Error(`Registry must use HTTPS: ${registryUrl}`);
+  }
+
+  parsed.hash = '';
+  parsed.search = '';
+  return parsed.toString().replace(/\/$/, '');
+}
+
+export function registryHostFromUrl(registryUrl = DEFAULT_REGISTRY_URL, { allowInsecure = false } = {}) {
+  return new URL(normalizeRegistryUrl(registryUrl, { allowInsecure })).host;
 }
 
 export function buildRegistryLine(scope = DEFAULT_SCOPE, registryUrl = DEFAULT_REGISTRY_URL) {
-  return `${scope}:registry=${registryUrl}`;
+  return `${scope}:registry=${normalizeRegistryUrl(registryUrl)}`;
 }
 
 export function buildTokenLine(registryUrl = DEFAULT_REGISTRY_URL, tokenValue) {
   return `//${registryHostFromUrl(registryUrl)}/:_authToken=${tokenValue}`;
 }
 
+export function buildTokenEnvReference(tokenEnv = DEFAULT_TOKEN_ENV) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokenEnv)) {
+    throw new Error(`Invalid token environment variable name: ${tokenEnv}`);
+  }
+
+  return '${' + tokenEnv + '}';
+}
+
+export function validateScope(scope = DEFAULT_SCOPE) {
+  if (!/^@[a-z0-9][a-z0-9._-]*$/i.test(scope)) {
+    throw new Error(`Invalid npm scope: ${scope}`);
+  }
+
+  return scope;
+}
+
 export function upsertNpmrc(content, {
   scope = DEFAULT_SCOPE,
   registryUrl = DEFAULT_REGISTRY_URL,
   tokenValue,
+  tokenEnv = DEFAULT_TOKEN_ENV,
+  storeToken = false,
+  allowInsecureRegistry = false,
 } = {}) {
-  if (!tokenValue) {
-    throw new Error('tokenValue is required');
+  const normalizedScope = validateScope(scope);
+  const normalizedRegistryUrl = normalizeRegistryUrl(registryUrl, { allowInsecure: allowInsecureRegistry });
+  const tokenValueForFile = storeToken
+    ? tokenValue
+    : buildTokenEnvReference(tokenEnv);
+
+  if (!tokenValueForFile) {
+    throw new Error(storeToken ? 'tokenValue is required when storeToken is enabled' : 'tokenEnv is required');
   }
 
   const existing = (content ?? '').replace(/\r\n/g, '\n');
-  const registryLinePrefix = `${scope}:registry=`;
-  const tokenLinePrefix = `//${registryHostFromUrl(registryUrl)}/:_authToken=`;
+  const registryLinePrefix = `${normalizedScope}:registry=`;
+  const tokenLinePrefix = `//${registryHostFromUrl(normalizedRegistryUrl, { allowInsecure: allowInsecureRegistry })}/:_authToken=`;
 
   const filteredLines = existing
     .split('\n')
@@ -40,8 +78,8 @@ export function upsertNpmrc(content, {
     filteredLines.push('');
   }
 
-  filteredLines.push(buildRegistryLine(scope, registryUrl));
-  filteredLines.push(buildTokenLine(registryUrl, tokenValue));
+  filteredLines.push(buildRegistryLine(normalizedScope, normalizedRegistryUrl));
+  filteredLines.push(buildTokenLine(normalizedRegistryUrl, tokenValueForFile));
 
   return `${filteredLines.join('\n')}\n`;
 }
@@ -54,3 +92,6 @@ export function hasRegistryConfig(content, {
   return normalized.includes(buildRegistryLine(scope, registryUrl));
 }
 
+export function redactSensitiveNpmrc(content) {
+  return (content ?? '').replace(/(:_authToken=)(.+)$/gm, '$1<redacted>');
+}