Merge pull request #1793 from zowe/chore/secrets/overview-md

chore(secrets): Add `OVERVIEW.md` for context on Zowe CLI and Zowe Explorer
zowe · Aug 29, 2023 · c73a89c · c73a89c
2 parents 3448092 + 701e5f9
commit c73a89c
Show file tree

Hide file tree

Showing 16 changed files with 96 additions and 44 deletions.
diff --git a/__tests__/__packages__/cli-test-utils/package.json b/__tests__/__packages__/cli-test-utils/package.json
@@ -44,7 +44,7 @@
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^14.18.28",
     "@types/uuid": "^8.3.0",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "eslint": "^8.22.0",
     "typescript": "^4.0.0"
   },

diff --git a/npm-shrinkwrap.json b/npm-shrinkwrap.json
diff --git a/package.json b/package.json
@@ -38,7 +38,7 @@
     "prepare": "husky install"
   },
   "dependencies": {
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "@zowe/perf-timing": "1.0.7"
   },
   "devDependencies": {

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -58,7 +58,7 @@
   },
   "dependencies": {
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "@zowe/perf-timing": "1.0.7",
     "@zowe/provisioning-for-zowe-sdk": "7.18.1",
     "@zowe/zos-console-for-zowe-sdk": "7.18.1",

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -51,7 +51,7 @@
   "devDependencies": {
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "chalk": "^4.1.0",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",

diff --git a/packages/provisioning/package.json b/packages/provisioning/package.json
@@ -52,7 +52,7 @@
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",
     "rimraf": "^2.6.3",

diff --git a/packages/secrets/CHANGELOG.md b/packages/secrets/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 All notable changes to the Zowe Secrets SDK package will be documented in this file.
 
+## Recent Changes
+
+- Added OVERVIEW document to package: provides context on the Secrets SDK transition and how it affects Zowe CLI and Zowe Explorer.
+
 ## `7.18.3`
 
 - Enhancement: Separated module resolution logic during installation; added more error handling to provide a more graceful installation process.

diff --git a/packages/secrets/OVERVIEW.md b/packages/secrets/OVERVIEW.md
@@ -0,0 +1,48 @@
+# Secrets SDK
+
+Secrets for Zowe SDK is a new development package used in the following Zowe releases:
+- Zowe CLI
+    - v7.18.0 and above from the NPM package
+    - Bundle v2.11.0 and above from [Zowe.org](https://www.zowe.org/download#download-v2)
+- Zowe Explorer and Zowe Explorer API
+    - v2.10.0 and above (v2 LTS)
+    - v1.22.5 and above (v1 LTS)
+
+The `keyring` module in this package replaces node-keytar. Node-keytar was developed by Atom, and is no longer maintained as of December 15th, 2022.
+
+## Impact on End Users
+
+### Zowe CLI
+
+CLI users should not be affected by this change. It is intended to be a drop-in replacement for node-keytar, so existing credentials will still be accessible.
+
+### Zowe Explorer
+
+- **Most** Zowe Explorer users should not be affected by this change.
+- Some Zowe Explorer users may be affected by this change. Specifically, users connecting over remote environments with Zowe Explorer are required to re-enter credentials. 
+    - Since keytar has been removed from VS Code for the next release, Zowe Explorer cannot access the local credential vault while the extension is running through a remote server.
+    - "Remote environments" include:
+        - Remote SSH
+        - Remote Tunnel
+        - Remote Docker
+    - [Click here](https://github.com/zowe/vscode-extension-for-zowe/wiki/Usage-in-Remote-Environments) for more information.
+
+## Impact on Extenders
+
+**CAUTION:** Regardless of whether you extend Zowe CLI or Zowe Explorer, developers that directly reference `keytar` as a dependency or dev dependency must use the new `keyring` module in `@zowe/secrets-for-zowe-sdk`.
+
+### Zowe CLI
+
+- Developers can continue using the credential manager utilities from Imperative.
+- Developers that indirectly use Zowe CLI to store and load secure credentials are not affected.
+
+### Zowe Explorer
+
+- Extenders that leverage Zowe Explorer API and Webpack (or another bundler) are required to update their extensions to provide prebuilds for the Secrets SDK. 
+    - This involves providing a folder named `prebuilds` with the Secrets SDK binaries alongside their extension root directory (same level as `package.json`).
+    - [Click here](https://github.com/zowe/zowe-cli/blob/master/packages/secrets/src/keyring/EXTENDERS.md#webpackingbundling-alongside-your-project) for more information on this process.
+- Extenders that do not use a bundler can continue using the credential manager utilities from Zowe Explorer API. These extensions are not affected by this change.
+
+---
+
+For more information on how to use the Secrets SDK, visit the [README for the `keyring` module](/packages/secrets/src/keyring/README.md).
diff --git a/packages/workflows/package.json b/packages/workflows/package.json
@@ -51,7 +51,7 @@
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",
     "rimraf": "^2.6.3",

diff --git a/packages/zosconsole/package.json b/packages/zosconsole/package.json
@@ -48,7 +48,7 @@
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",
     "rimraf": "^2.6.3",

diff --git a/packages/zosfiles/package.json b/packages/zosfiles/package.json
@@ -53,7 +53,7 @@
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "@zowe/zos-uss-for-zowe-sdk": "7.18.1",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",

diff --git a/packages/zosjobs/package.json b/packages/zosjobs/package.json
@@ -52,7 +52,7 @@
     "@types/node": "^14.18.28",
     "@zowe/cli-test-utils": "7.18.1",
     "@zowe/core-for-zowe-sdk": "7.18.1",
-    "@zowe/imperative": "5.18.0",
+    "@zowe/imperative": "5.18.1",
     "eslint": "^8.22.0",
     "madge": "^4.0.1",
     "rimraf": "^2.6.3",