@fprad0/skill-master-mcp 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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.
+- Add a `skill-master-menu` option to run the global npm update flow.
+- Document npm-based auto-update usage for operators and scheduled tasks.
+
 ## [0.0.4] - 2026-06-26
 
 - Add `skill_master_activation_check` to decide when the MCP should activate for a prompt.

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
@@ -108,16 +110,17 @@ npx -y @fprad0/skill-master-mcp@latest
 
 Estado atual validado em `2026-06-26`:
 
-- pacote publico publicado: `@fprad0/skill-master-mcp@0.0.2`
-- dist-tag `latest` apontando para `0.0.2`
+- pacote publico publicado: `@fprad0/skill-master-mcp@0.0.5`
+- dist-tag `latest` apontando para `0.0.5`
 - workflow `Publish Skill Master to npmjs` concluido com sucesso
 - `npm install` e `npx` confirmados
 
-O pacote `0.0.3` adiciona o menu operacional. Depois da publicacao dessa versao, os comandos globais principais ficam:
+Comandos globais principais:
 
 ```bash
 skill-master-mcp
 skill-master-menu
+skill-master-update
 skill-master-configure-private-registry
 ```
 
@@ -127,6 +130,20 @@ O `skill-master-mcp` deve continuar reservado para clientes MCP via `stdio`. Par
 skill-master-menu
 ```
 
+Para atualizar a instalacao global via npm sem iniciar o servidor MCP:
+
+```bash
+skill-master-update
+```
+
+Esse comando executa o equivalente a:
+
+```bash
+npm install -g @fprad0/skill-master-mcp@latest --registry=https://registry.npmjs.org
+```
+
+Use `skill-master-update` antes de abrir ou depois de fechar o cliente MCP. Evite atualizar o pacote enquanto `skill-master-mcp` esta rodando em `stdio`, porque o cliente pode manter o processo antigo carregado ate ser reiniciado.
+
 Leia:
 
 - [Guia de publicacao no npm publico](docs/operations/GUIA_NPM_PUBLICO.md)
@@ -214,6 +231,41 @@ Cliente: chama skill_master_activation_check.
 Cliente: se ativar, chama skill_master_recommend ou segue as recomendacoes retornadas.
 ```
 
+## Atualizacao automatica via npm
+
+Para instalacoes feitas por `npm install -g`, o caminho seguro de auto-update e executar `skill-master-update` fora do processo MCP.
+
+Uso manual:
+
+```bash
+skill-master-update
+```
+
+Uso em agendamento Linux/macOS:
+
+```bash
+skill-master-update
+```
+
+Uso em agendamento Windows:
+
+```powershell
+skill-master-update
+```
+
+Validacao sem aplicar update:
+
+```bash
+skill-master-update --dry-run
+```
+
+Regra operacional:
+
+- nao atualizar dentro do processo `skill-master-mcp` em `stdio`
+- atualizar antes de iniciar o cliente MCP ou em janela agendada
+- reiniciar Codex, Claude, Gemini ou outro cliente MCP depois da atualizacao
+- para desenvolvimento com clone, continuar usando o launcher por manifesto e `git pull --ff-only`
+
 ## Arquivos principais
 
 - [Plano geral](docs/PLANO_SKILL_MASTER_00_01.md)

package/VERSION.md

@@ -2,8 +2,8 @@
 
 Versão funcional planejada: `00.02`
 
-Versão técnica para empacotamento semântico: `0.0.4`
+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.4`.
+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/bin/skill-master-menu.mjs

@@ -35,6 +35,11 @@ const commands = {
       '--registry=https://registry.npmjs.org',
     ],
   },
+  updateGlobal: {
+    label: 'Atualizar pacote global via npm',
+    command: process.execPath,
+    args: [join(rootDir, 'bin', 'skill-master-update.mjs')],
+  },
   privateRegistry: {
     label: 'Configurar registry privado GitHub Packages',
     command: process.execPath,
@@ -47,7 +52,8 @@ const menuItems = [
   ['2', commands.check],
   ['3', commands.build],
   ['4', commands.publicNpm],
-  ['5', commands.privateRegistry],
+  ['5', commands.updateGlobal],
+  ['6', commands.privateRegistry],
 ];
 
 function readJson(relativePath) {
@@ -76,6 +82,9 @@ Uso:
   skill-master-menu --status
   skill-master-menu --help
 
+Opcao 5 do menu:
+  atualiza o pacote global com npm install -g @fprad0/skill-master-mcp@latest
+
 O comando de menu e voltado para operacao humana. O binario MCP stdio continua sendo:
   skill-master-mcp
 `);

package/bin/skill-master-update.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+
+const DEFAULT_PACKAGE = '@fprad0/skill-master-mcp@latest';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+function printHelp() {
+  console.log(`Skill Master Update
+
+Uso:
+  skill-master-update
+  skill-master-update --dry-run
+  skill-master-update --package @fprad0/skill-master-mcp@latest
+  skill-master-update --registry https://registry.npmjs.org
+
+Este comando atualiza a instalacao global via npm. Ele deve ser executado fora
+do processo MCP stdio para evitar substituir arquivos enquanto o servidor esta
+em uso por um cliente.
+`);
+}
+
+function readOption(args, name, fallback) {
+  const index = args.indexOf(name);
+  if (index === -1) {
+    return fallback;
+  }
+
+  return args[index + 1] || fallback;
+}
+
+function buildInstallArgs(args) {
+  const packageName = readOption(args, '--package', DEFAULT_PACKAGE);
+  const registry = readOption(args, '--registry', DEFAULT_REGISTRY);
+  return ['install', '-g', packageName, `--registry=${registry}`];
+}
+
+function run(command, args) {
+  return new Promise((resolve) => {
+    console.log(`> ${command} ${args.join(' ')}`);
+    const child = spawn(command, args, {
+      env: process.env,
+      shell: process.platform === 'win32',
+      stdio: 'inherit',
+    });
+
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return 0;
+  }
+
+  const installArgs = buildInstallArgs(args);
+
+  if (args.includes('--dry-run')) {
+    console.log(['npm', ...installArgs].join(' '));
+    return 0;
+  }
+
+  console.log('Atualizando Skill Master MCP por npm global.');
+  console.log('Feche/reinicie clientes MCP depois da atualizacao para carregar a nova versao.\n');
+
+  return run('npm', installArgs);
+}
+
+process.exitCode = await main();

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.4",
-  "publishedAt": "2026-06-26T14:10: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": "545b4bb"
+    "commit": "c203ead"
   },
   "node": {
     "minimum": "18.0.0"
@@ -19,7 +19,7 @@
     "buildCommand": "npm run build"
   },
   "changelog": [
-    "Canal beta acompanha a nova avaliacao de ativacao por prompt.",
-    "Clientes podem chamar skill_master_activation_check antes de decidir usar recomendacoes de skills."
+    "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.4",
-  "publishedAt": "2026-06-26T14:10: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": "545b4bb"
+    "commit": "c203ead"
   },
   "node": {
     "minimum": "18.0.0"
@@ -19,8 +19,8 @@
     "buildCommand": "npm run build"
   },
   "changelog": [
-    "Nova tool skill_master_activation_check para decidir ativacao por prompt.",
-    "Aliases explicitos suportados: skill-master, skill_master e skill-master-mcp.",
-    "Ativacao inferida quando o catalogo encontra skills relevantes para a tarefa."
+    "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.4",
+  "version": "0.0.6",
   "private": false,
   "type": "module",
   "description": "Personal MCP server that catalogs, recommends and reports skills with update-aware metadata.",
@@ -8,7 +8,8 @@
   "bin": {
     "skill-master-configure-private-registry": "./bin/skill-master-configure-private-registry.mjs",
     "skill-master-menu": "./bin/skill-master-menu.mjs",
-    "skill-master-mcp": "./bin/skill-master.mjs"
+    "skill-master-mcp": "./bin/skill-master.mjs",
+    "skill-master-update": "./bin/skill-master-update.mjs"
   },
   "files": [
     "bin",

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>');
+}