add secrets SDK tests, imperative typedoc

Signed-off-by: Trae Yelovich <[email protected]>

Author: traeok

packages/imperative/src/security/src/DefaultCredentialManager.ts

@@ -110,6 +110,8 @@ export class DefaultCredentialManager extends AbstractCredentialManager {
                 break;
         }
 
+        Logger.getImperativeLogger().trace(`[DefaultCredentialManager] Persist value (win32): ${this.persistValueWin32}`);
+
         /* Gather all services. We will load secure properties for the first
         * successful service found in the order that they are placed in this array.
         */

packages/imperative/src/security/src/doc/IDefaultCredentialManagerOptions.ts

@@ -11,15 +11,24 @@
 
 import type { ICredentialManagerOptions } from "./ICredentialManagerOptions";
 
+/** 
+ * Used to map value in `imperative.json` to respective value for Win32 persistence flag in CredentialA. See {@link PersistenceValue} for flag values. 
+ */
 export enum PersistenceLevel {
     SessionOnly = "session",
     LocalMachine = "local_machine",
     Enterprise = "enterprise"
 }
 
+/** 
+ * Note: Values map to `Persist` variable in [CredentialA](https://learn.microsoft.com/en-us/windows/win32/api/wincred/ns-wincred-credentiala) structure.
+ */
 export enum PersistenceValue {
+    // CRED_PERSIST_SESSION
     SessionOnly = 1,
+    // CRED_PERSIST_LOCAL_MACHINE
     LocalMachine = 2,
+    // CRED_PERSIST_ENTERPRISE
     Enterprise = 3
 }
 

packages/secrets/src/keyring/__test__/index.spec.mjs

@@ -22,6 +22,8 @@ const randomAsciiString = (len) => {
     return str;
 };
 
+const isWin32 = process.platform === "win32";
+
 const TEST_CREDENTIALS = [
     { service: "TestKeyring", account: "TestASCII" },
     { service: "TestKeyring", account: "TestUTF8" },
@@ -32,6 +34,9 @@ const TEST_CREDENTIALS = [
     { service: "TestEmptyAccount", account: "" },
     { service: "", account: "TestEmptyService" },
     { service: "TestKeyring", account: "PwNullTerm" },
+    { service: "TestKeyring", account: "PersistSession", password: "SessionPw" },
+    { service: "TestKeyring", account: "PersistLocalMachine", password: "LocalMachinePw" },
+    { service: "TestKeyring", account: "PersistEnterprise", password: "EnterprisePw" },
 ];
 
 test.serial("get/setPassword with binary data", async (t) => {
@@ -112,6 +117,29 @@ test.serial("get/setPassword fails with null/undefined data", async (t) => {
     }
 });
 
+if (isWin32) {
+    // Unit test specific to Windows API call (needs to be called before rest of Win32 tests)
+    test.serial(
+        "get/setPassword works for all 3 Win32 persistence levels",
+        async (t) => {
+            const credsToSave = TEST_CREDENTIALS.slice(-3).map((c, i) => ({ ...c, persist: i + 1 }));
+
+            try {
+                for (const cred of credsToSave) {
+                    await setPassword(cred.service, cred.account, cred.password, cred.persist);
+                    t.is(await getPassword(cred.service, cred.account), cred.password);
+                }
+            } catch (err) {
+                t.fail(
+                    "setPassword should not throw an exception when setting credentials with a persistence flag"
+                );
+            }
+
+            t.pass();
+        }
+    );
+}
+
 test.serial(
     "get/setPassword with password containing extra null terminators",
     async (t) => {
@@ -146,6 +174,9 @@ test.serial(
             },
             { account: "TestUTF16", password: "🌞🌙🌟🌴" },
             { account: "PwNullTerm", password: "PW\x00" },
+            { account: "PersistSession", password: "SessionPw" },
+            { account: "PersistLocalMachine", password: "LocalMachinePw" },
+            { account: "PersistEnterprise", password: "EnterprisePw" }
         ];
         const actual = await findCredentials("TestKeyring");
         t.is(
@@ -219,7 +250,7 @@ test("deletePassword deletes all test credentials", async (t) => {
 });
 
 // Unit tests specific to Windows API calls
-if (process.platform === "win32") {
+if (isWin32) {
     test.serial(
         "setPassword fails when blob exceeds CRED_MAX_CREDENTIAL_BLOB_SIZE",
         async (t) => {