scp-next 1.1.8 → 1.1.10

package/guides/HOST_VERIFICATION_TROUBLESHOOTING.md

@@ -0,0 +1,146 @@
+# Troubleshoot SSH host verification
+
+Use this procedure when `scp-next` reports `HostVerificationError`. It applies to SFTP
+transfers and explicit remote-command connections. Troubleshooting never requires disabling
+verification.
+
+## 1. Check the endpoint and trust settings
+
+Read the host, port, selected known-hosts file, and explicit-fingerprint status in the error.
+The default port is `22`; the default trust file is `~/.ssh/known_hosts`. `~` expands to the
+current user's home directory. A custom `knownHostsFile` must be accessible even when an
+explicit `hostFingerprint` is configured. An inaccessible default file can be skipped when
+an explicit fingerprint is configured.
+
+- **File not found:** check the selected path and the account running the process.
+- **File could not be read:** check permissions and whether the path is a readable file.
+- **No usable matching keys:** the file was read, but supplied no supported matching entries.
+- **Connection-time failure:** the host key could not be verified. This message alone does
+  not establish that a previously trusted key changed.
+
+Use the same hostname or IP address as the transfer, not an SSH configuration alias that
+resolves to another endpoint. `scp-next` supports exact plain host entries and bracketed
+`[host]:port` entries. It does not interpret hashed hostnames, wildcard patterns, or OpenSSH
+marker entries such as `@cert-authority` and `@revoked`. Ordinary `ssh` can therefore succeed
+with a trust file that `scp-next` cannot use. Use a verified explicit fingerprint or a
+separate plain-entry trust file if those limitations apply. Plain entries expose hostnames
+to anyone who can read the file; keep access appropriately restricted.
+
+Do not convert a revoked key into a plain trusted entry or use a fingerprint to bypass
+revocation. If you rely on OpenSSH certificate or revocation policy, resolve the unsupported
+policy with your administrator before using `scp-next`; its parser does not enforce that policy.
+
+## 2. Scan into a temporary file and inspect fingerprints
+
+Install OpenSSH's `ssh-keyscan` and `ssh-keygen` commands first. Replace `your-host` and
+`2222` below with the configured hostname or single IP address and port. Do not use a CIDR
+range, an option, or a comma-separated host list. These commands contact the server but do
+not add anything to your trusted file. Do not use `-H`, which hashes hostnames.
+
+> Warning: scanning does not authenticate the server. An intercepted scan can return an
+> attacker's keys. Do not trust any result until you complete the independent verification
+> in the next section. See the [OpenSSH ssh-keyscan manual](https://man.openbsd.org/ssh-keyscan).
+
+### POSIX shell (macOS or Linux)
+
+Run in a dedicated shell session or script; failure branches exit that session.
+
+```sh
+server_host='your-host'
+server_port='2222'
+scan_file=$(mktemp) || exit 1
+
+if ! ssh-keyscan -p "$server_port" "$server_host" > "$scan_file"; then
+  echo 'Scan failed; do not update trust.' >&2
+  rm -- "$scan_file"
+  exit 1
+fi
+if ! awk 'NF >= 3 && $1 !~ /^#/ { found=1 } END { exit !found }' "$scan_file"; then
+  echo 'No host keys returned; do not update trust.' >&2
+  rm -- "$scan_file"
+  exit 1
+fi
+if ! ssh-keygen -l -E sha256 -f "$scan_file"; then
+  echo 'Fingerprint inspection failed; do not update trust.' >&2
+  rm -- "$scan_file"
+  exit 1
+fi
+printf 'Temporary scan file: %s\n' "$scan_file"
+```
+
+### PowerShell (Windows)
+
+Explicit UTF-8 encoding avoids Windows PowerShell's default UTF-16 file output.
+
+```powershell
+$serverHost = 'your-host'
+$serverPort = '2222'
+$scanFile = [System.IO.Path]::GetTempFileName()
+try {
+    $scanLines = @(& ssh-keyscan -p "$serverPort" "$serverHost")
+    if (-not $? -or $LASTEXITCODE -ne 0) { throw 'Scan failed; do not update trust.' }
+    $keyLines = @($scanLines | Where-Object {
+        $_ -notmatch '^#' -and $_ -match '^\S+\s+\S+\s+\S+'
+    })
+    if ($keyLines.Count -eq 0) { throw 'No host keys returned; do not update trust.' }
+    [System.IO.File]::WriteAllLines(
+        $scanFile, [string[]]$scanLines, [System.Text.UTF8Encoding]::new($false)
+    )
+    & ssh-keygen -l -E sha256 -f "$scanFile"
+    if (-not $? -or $LASTEXITCODE -ne 0) { throw 'Fingerprint inspection failed; do not update trust.' }
+    Write-Output "Temporary scan file: $scanFile"
+} catch {
+    Remove-Item -LiteralPath $scanFile
+    throw
+}
+```
+
+`ssh-keygen -l -E sha256` displays SHA-256 fingerprints for inspection. See the
+[OpenSSH ssh-keygen manual](https://man.openbsd.org/ssh-keygen). A scan may return multiple
+key types or only some of the server's keys; do not assume every key was collected.
+
+## 3. Verify each key independently
+
+Compare the fingerprint and key type of every key you intend to trust with values from a
+trusted server console, administrator, or authenticated provider interface. Repeating the
+scan over the same connection is not independent verification. If no trusted source is
+available, stop and contact the administrator.
+
+If a previously trusted key differs, investigate before changing trust. Confirm an authorized
+key rotation, server rebuild, or endpoint change through the independent source. Do not
+assume that a changed key is harmless.
+
+## 4. Save only verified keys
+
+Review the temporary file in a text editor. Copy only independently verified key lines to
+the exact `knownHostsFile` selected by your configuration. Do not append the entire scan
+automatically. Create the parent directory if necessary and restrict write access to trusted
+accounts. Preserve plain host fields, key types, and base64 keys; save the file as UTF-8.
+
+For an authorized replacement, back up the existing file first. Remove only the affected
+obsolete keys, preserving unrelated hosts and aliases. A line can contain several
+comma-separated aliases; split it if necessary rather than deleting trust for other hosts.
+Do not leave obsolete keys trusted merely because adding a new key makes the connection work.
+
+Alternatively, configure `hostFingerprint` with a verified `SHA256:...` value. Explicit
+fingerprints and matching known-hosts keys form a combined allowed set; the fingerprint does
+not override the file. Adding a verified file entry does not remove a stale explicit
+fingerprint. Review and update both sources after an authorized rotation.
+
+## 5. Retry and clean up
+
+Retry the original transfer. If it still fails, recheck the endpoint, account, selected file,
+explicit fingerprint, and negotiated key type. Do not repeatedly append scan results.
+Remove the temporary file after troubleshooting:
+
+```sh
+# POSIX shell
+rm -- "$scan_file"
+```
+
+```powershell
+# PowerShell
+Remove-Item -LiteralPath $scanFile
+```
+
+`scp-next` does not run these commands, scan hosts, or write trust files for you.

package/guides/HOST_VERIFICATION_TROUBLESHOOTING_PLAN.md

@@ -1,7 +1,8 @@
 # Host verification troubleshooting plan
 
-Status: Proposed. Implementation requires user confirmation. Creating this plan does not
-authorize changes to runtime code, SSH trust files, or server connections.
+Status: Implemented after user approval. See the
+[host verification troubleshooting guide](HOST_VERIFICATION_TROUBLESHOOTING.md).
+The implementation does not scan hosts, modify SSH trust files, or disable verification.
 
 ## Goal
 
@@ -9,7 +10,7 @@ Replace generic SSH troubleshooting tips with concise guidance to scan, verify,
 host keys. Show the configured endpoint and trust file, and distinguish missing trust
 information from a possible key mismatch when the failure path provides that evidence.
 
-## Current limitations
+## Baseline limitations (before implementation)
 
 - `hostVerificationTroubleshooting()` in `src/client/transport.ts` suggests `ssh <host>`
   without the configured port or known-hosts path.
@@ -105,3 +106,19 @@ artifact. Inspect the final diff and package contents before handoff.
 
 The package currently includes all of `guides` in its published files. This plan will therefore
 be included in a future package unless its location or packaging policy is deliberately changed.
+
+### Implementation validation
+
+Typecheck, lint, all 102 tests, package build, ESM/CommonJS smoke checks, CLI shebang,
+documentation links, the full documentation build (including SEO and PWA checks), and
+`npm pack --dry-run` passed.
+
+The initial Webpack schema failure came from a stale installation of Webpack 5.109.2, not
+an invalid configuration. Synchronizing installed dependencies with the committed lockfile
+restored Webpack 5.111.1, which supports `optimization.minimizeOptions`. The production-build
+test now has a 60-second timeout rather than the default five seconds. Manifest and lockfile
+versions and build configuration remain unchanged.
+
+The README troubleshooting link uses the repository URL so TypeDoc does not copy the
+handwritten Markdown guide into generated API media. Documentation links are checked again
+after the Pages build to verify the generated output remains free of Markdown source files.

package/guides/NPM_TRUSTED_PUBLISHING.md

@@ -0,0 +1,205 @@
+# Publish automatically to npm with GitHub Actions OIDC
+
+Migrate `scp-next` from `NPM_TOKEN` to npm trusted publishing while preserving automatic
+publication on pushes to `release/v*` branches. This guide assumes the package already
+exists and you have configured its trusted publisher. It describes changes to make; it
+does not mean the repository's workflow has already been migrated.
+
+OpenID Connect (OIDC) lets GitHub issue a short-lived, signed workflow identity that npm
+checks before authorizing publication. You do not store a permanent npm publishing token
+in the repository. See [GitHub's OIDC explanation](https://docs.github.com/en/actions/concepts/security/openid-connect).
+
+## 1. Verify the trusted publisher
+
+Sign in to npm as `mazeyqian` and open the existing `scp-next` package's settings. Confirm
+that the GitHub Actions trusted publisher has these values:
+
+| Field                | Value             |
+| :------------------- | :---------------- |
+| Organization or user | `chengchuu`       |
+| Repository           | `scp-next`        |
+| Workflow filename    | `publish-npm.yml` |
+| Allowed action       | Direct publishing |
+
+Enable **Allow npm publish**; staging-only permission requires human approval. Enter the
+workflow filename, not `.github/workflows/publish-npm.yml`. If you configured an environment,
+record its exact name for step 3. See [npm's trusted-publisher configuration](https://docs.npmjs.com/trusted-publishers/).
+
+The GitHub owner and npm account do not need matching usernames. `mazeyqian` manages the
+npm package; `chengchuu` identifies the GitHub repository owner. Keep the npm package name
+as `scp-next`.
+
+## 2. Preserve the existing triggers and toolchain
+
+Open [the publishing workflow](../.github/workflows/publish-npm.yml). Keep:
+
+- Push publication from `release/v*` branches.
+- PR validation for `main` and `release/v*` without publication.
+- `needs: test` and the publish job's `github.event_name == 'push'` condition.
+- The current test-only behavior of `workflow_dispatch`.
+- GitHub-hosted `ubuntu-latest` runners, Node 22, npm 11.18.0, and `npm install`.
+- The npm registry URL `https://registry.npmjs.org/` in the publish job's Node setup.
+
+OIDC requires Node 22.14.0 or later and npm 11.5.1 or later, so this CI toolchain qualifies.
+See [npm's requirements](https://docs.npmjs.com/trusted-publishers/).
+
+Do not upgrade to npm 12 as part of the authentication migration. Its install-time defaults
+change dependency-script, native-build, Git-dependency, and remote-URL behavior; assess those
+separately. See [the npm security announcement](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/).
+
+Keep `pnpm-lock.yaml` as the committed lockfile. CI intentionally uses `npm install`, which
+does not consume that lockfile; OIDC does not make dependency resolution reproducible.
+
+## 3. Scope permissions to the publishing job
+
+Replace the workflow-level write permissions with:
+
+```yaml
+permissions:
+  contents: read
+```
+
+Add this block directly under `jobs.publish`, alongside `needs`, `runs-on`, and `if`:
+
+```yaml
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+```
+
+These permissions have separate purposes:
+
+- `id-token: write` enables npm OIDC authentication.
+- `packages: write` preserves GitHub Packages publication.
+- `contents: write` preserves the existing Git-tag creation and push.
+
+The test job inherits read-only permissions. Do not grant it publishing permissions.
+See [npm's workflow configuration](https://docs.npmjs.com/trusted-publishers/).
+
+If step 1 identified an environment, add that exact `environment` name to the publish job.
+Leave it unset otherwise. Required reviewers would prevent unattended publication.
+
+## 4. Replace only the npm authentication step
+
+Replace the current **Publish to npm** step with:
+
+```yaml
+- name: Publish to npm
+  run: npm publish --access public
+```
+
+Remove its `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` entry. Check that no job-level or
+workflow-level npm write token remains. npm detects OIDC automatically; do not add an npm
+login step or manually request the identity token. See [npm's authentication behavior](https://docs.npmjs.com/trusted-publishers/).
+
+Keep the GitHub Packages registry setup, scoped package-name change, and
+`NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` on its publication step. That registry still
+uses GitHub authentication. Keep the restore step and post-publication Git tag.
+See [GitHub Packages authentication](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages#authenticating-to-the-destination-repository).
+
+[The Pages workflow](../.github/workflows/pages.yml) needs no npm-authentication changes.
+Its OIDC permission serves Pages deployment. Do not remove that permission.
+
+## 5. Review release safety before the first push
+
+Protect `release/v*` branches and publishing-workflow changes. Anyone who can run altered
+code in the trusted publishing job may be able to publish; OIDC does not establish that
+the code is safe.
+
+Consider these separate reliability improvements before enabling unattended releases:
+
+- Serialize publishing jobs with a package-wide concurrency group, not one group per branch.
+  Do not cancel a publication already running. GitHub's default concurrency behavior replaces
+  an older pending run; use `queue: max` if you need multiple pending releases, and account
+  for queue limits and ordering. See [GitHub concurrency controls](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency).
+- Define whether an already-published version should stop the run or be skipped after verifying
+  the expected artifact. Do not treat every registry error as an absent version.
+- Make recovery from partial npm/GitHub Packages publication explicit. Separating registry jobs
+  is an option, but not a prerequisite for OIDC.
+- Check existing Git tags against the intended commit; never overwrite a conflicting release tag.
+
+The existing workflow does not provide these safeguards. A minimal OIDC migration preserves
+that limitation; decide on hardening separately rather than assuming authentication fixes it.
+
+## 6. Validate the proposed workflow and release
+
+Review the YAML diff before merging. Confirm that only the intended npm authentication and
+permission settings changed, and that the snippets were inserted at the correct indentation.
+Use a GitHub Actions-aware validator if one is available.
+
+From the repository root, run the established package checks:
+
+```bash
+npm run clean
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run docs:links
+npm pack --dry-run
+git diff --check
+```
+
+Inspect the package contents for the ESM/CJS builds, declarations, CLI entry, README, license,
+and guides. Preserve the existing `prepublishOnly` checks; do not disable lifecycle scripts
+to bypass release validation. These checks are instructions for migration, not results
+reported by this document.
+
+Prepare an intentional release with an unpublished `package.json.version` and update
+[the changelog](CHANGELOG.md). Check the published versions without publishing:
+
+```bash
+npm view scp-next versions --json --registry=https://registry.npmjs.org/
+```
+
+If the registry lookup fails, resolve the failure before deciding that the version is unused.
+Also check the corresponding GitHub Packages version and Git tag. Branch pushes do not bump
+versions automatically.
+
+## 7. Push the release and verify publication
+
+**Warning:** pushing the migrated workflow and release to a matching `release/v*` branch
+can publish a real package version. PR checks and manual workflow runs do not prove that
+OIDC publication works.
+
+1. Commit the approved workflow and release changes.
+2. Push the intended release commit to the matching release branch.
+3. Open the **Publish npm Packages** run in GitHub Actions.
+4. Confirm that validation and the npm publication step succeed without `NPM_TOKEN`.
+5. Verify the exact version on npm, then verify GitHub Packages and the Git tag independently.
+6. Check the npm provenance information when publishing a public package from the public repository.
+
+Trusted publishing generates provenance automatically when its conditions are met; an explicit
+`--provenance` flag is not required. See [npm provenance documentation](https://docs.npmjs.com/generating-provenance-statements/).
+
+Local checks and dry runs cannot verify registry authorization. Do not use `npm whoami`
+as an OIDC publishing test. See [npm's OIDC limitations](https://docs.npmjs.com/trusted-publishers/).
+
+## 8. Remove obsolete credentials after verification
+
+After a successful token-free npm publication:
+
+1. Remove the unused `NPM_TOKEN` secret from this repository's Actions secrets.
+2. Check whether other repositories or tools still use the same token.
+3. Revoke the npm token only after those consumers have migrated or stopped using it.
+
+Keep `GITHUB_TOKEN` authentication for GitHub Packages. Repeat the package-specific trust
+setup and workflow review for other npm repositories; this migration does not authorize them.
+
+## Troubleshoot or pause the rollout
+
+- **Authentication fails:** verify the exact owner, repository, workflow filename, environment,
+  direct-publish permission, job-level OIDC permission, and toolchain. Confirm that the
+  package repository URL still identifies `chengchuu/scp-next`.
+- **npm succeeds but GitHub Packages fails:** record the published version and run commit.
+  Do not blindly rerun the combined publish job. Arrange a reviewed recovery that publishes
+  only the missing artifact and creates the tag after verifying the release commit.
+- **A version or tag already exists:** inspect its contents or commit before deciding how to
+  recover. Do not overwrite it or hide the failure.
+- **You need to stop publishing:** pause the publishing workflow or block release-branch pushes
+  while investigating. Reverting YAML does not undo a published package.
+
+Treat a published version as immutable. For an incorrect release, plan a corrected version
+and, if appropriate, deprecate the affected version; do not make unpublishing part of routine
+rollback. See [npm's unpublish policy](https://docs.npmjs.com/policies/unpublish/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scp-next",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "An SCP CLI and library for secure SSH file transfers using SFTP.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,7 +26,6 @@
     "dist",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md",
     "guides"
   ],
   "scripts": {
@@ -78,7 +77,7 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "mazey": "^5.6.1",
+    "mazey": "^5.10.4",
     "ssh2": "^1.17.0",
     "ssh2-sftp-client": "^11.0.0",
     "zod": "^3.23.8"
@@ -108,7 +107,7 @@
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1",
     "vitest": "^4.1.9",
-    "webpack": "^5.108.4",
+    "webpack": "^5.111.1",
     "webpack-cli": "^7.2.1",
     "webpack-dev-server": "^6.0.0"
   },