Merge pull request #23 from jeskew/feature/credential-provider-base

Add a base credential provider package

Author: jeskew

packages/credential-provider-base/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+*.js
+*.js.map
+*.d.ts

packages/credential-provider-base/__tests__/CredentialError.ts

@@ -0,0 +1,11 @@
+import { CredentialError } from "../lib/CredentialError";
+
+describe("CredentialError", () => {
+  it("should direct the chain to proceed to the next link by default", () => {
+    expect(new CredentialError("PANIC").tryNextLink).toBe(true);
+  });
+
+  it("should allow errors to halt the chain", () => {
+    expect(new CredentialError("PANIC", false).tryNextLink).toBe(false);
+  });
+});

packages/credential-provider-base/__tests__/chain.ts

@@ -0,0 +1,71 @@
+import { chain } from "../lib/chain";
+import { fromCredentials } from "../lib/fromCredentials";
+import { isCredentials } from "../lib/isCredentials";
+import { CredentialError } from "../lib/CredentialError";
+
+describe("chain", () => {
+  it("should distill many credential providers into one", async () => {
+    const provider = chain(
+      fromCredentials({ accessKeyId: "foo", secretAccessKey: "bar" }),
+      fromCredentials({ accessKeyId: "baz", secretAccessKey: "quux" })
+    );
+
+    expect(isCredentials(await provider())).toBe(true);
+  });
+
+  it("should return the resolved value of the first successful promise", async () => {
+    const creds = { accessKeyId: "foo", secretAccessKey: "bar" };
+    const provider = chain(
+      () => Promise.reject(new CredentialError("Move along")),
+      () => Promise.reject(new CredentialError("Nothing to see here")),
+      fromCredentials(creds)
+    );
+
+    expect(await provider()).toEqual(creds);
+  });
+
+  it("should not invoke subsequent providers one resolves", async () => {
+    const creds = { accessKeyId: "foo", secretAccessKey: "bar" };
+    const providers = [
+      jest.fn(() => Promise.reject(new CredentialError("Move along"))),
+      jest.fn(() => Promise.resolve(creds)),
+      jest.fn(() => fail("This provider should not be invoked"))
+    ];
+
+    expect(await chain(...providers)()).toEqual(creds);
+    expect(providers[0].mock.calls.length).toBe(1);
+    expect(providers[1].mock.calls.length).toBe(1);
+    expect(providers[2].mock.calls.length).toBe(0);
+  });
+
+  it("should not invoke subsequent providers one is rejected with a terminal error", async () => {
+    const providers = [
+      jest.fn(() => Promise.reject(new CredentialError("Move along"))),
+      jest.fn(() => Promise.reject(new CredentialError("Stop here", false))),
+      jest.fn(() => fail("This provider should not be invoked"))
+    ];
+
+    await chain(...providers)().then(
+      () => {
+        throw new Error("The promise should have been rejected");
+      },
+      err => {
+        expect(err.message).toBe("Stop here");
+        expect(providers[0].mock.calls.length).toBe(1);
+        expect(providers[1].mock.calls.length).toBe(1);
+        expect(providers[2].mock.calls.length).toBe(0);
+      }
+    );
+  });
+
+  it("should reject chains with no links", async () => {
+    await chain()().then(
+      () => {
+        throw new Error("The promise should have been rejected");
+      },
+      () => {
+        /* Promise rejected as expected */
+      }
+    );
+  });
+});

packages/credential-provider-base/__tests__/fromCredentials.ts

@@ -0,0 +1,18 @@
+import { CredentialProvider, Credentials } from "@aws/types";
+import { fromCredentials } from "../lib/fromCredentials";
+
+describe("fromCredentials", () => {
+  it("should convert credentials into a credential provider", async () => {
+    const credentials: Credentials = {
+      accessKeyId: "foo",
+      secretAccessKey: "bar",
+      sessionToken: "baz",
+      expiration: Math.floor(Date.now().valueOf() / 1000)
+    };
+    const provider: CredentialProvider = fromCredentials(credentials);
+
+    expect(typeof provider).toBe("function");
+    expect(provider()).toBeInstanceOf(Promise);
+    expect(await provider()).toEqual(credentials);
+  });
+});

packages/credential-provider-base/__tests__/isCredentials.ts

@@ -0,0 +1,69 @@
+import { isCredentials } from "../lib/isCredentials";
+
+describe("isCredentials", () => {
+  const minimalCredentials = { accessKeyId: "foo", secretAccessKey: "bar" };
+
+  it("should reject scalar values", () => {
+    for (let scalar of ["foo", 12, 1.2, true, null, undefined]) {
+      expect(isCredentials(scalar)).toBe(false);
+    }
+  });
+
+  it("should accept an object with an accessKeyId and secretAccessKey", () => {
+    expect(isCredentials(minimalCredentials)).toBe(true);
+  });
+
+  it("should reject objects where accessKeyId is not a string", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        accessKeyId: 123
+      })
+    ).toBe(false);
+  });
+
+  it("should reject objects where secretAccessKey is not a string", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        secretAccessKey: 123
+      })
+    ).toBe(false);
+  });
+
+  it("should accept credentials with a sessionToken", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        sessionToken: "baz"
+      })
+    ).toBe(true);
+  });
+
+  it("should reject credentials where sessionToken is not a string", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        sessionToken: 123
+      })
+    ).toBe(false);
+  });
+
+  it("should accept credentials with an expiration", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        expiration: 0
+      })
+    ).toBe(true);
+  });
+
+  it("should reject credentials where expiration is not a number", () => {
+    expect(
+      isCredentials({
+        ...minimalCredentials,
+        expiration: "quux"
+      })
+    ).toBe(false);
+  });
+});

packages/credential-provider-base/__tests__/memoize.ts

@@ -0,0 +1,40 @@
+import { memoize } from "../lib/memoize";
+
+describe("memoize", () => {
+  it("should cache the resolved provider for permanent credentials", async () => {
+    const creds = { accessKeyId: "foo", secretAccessKey: "bar" };
+    const provider = jest.fn(() => Promise.resolve(creds));
+    const memoized = memoize(provider);
+
+    expect(await memoized()).toEqual(creds);
+    expect(provider.mock.calls.length).toBe(1);
+    expect(await memoized()).toEqual(creds);
+    expect(provider.mock.calls.length).toBe(1);
+  });
+
+  it("should invoke provider again when credentials expire", async () => {
+    const clockMock = (Date.now = jest.fn());
+    clockMock.mockReturnValue(0);
+    const provider = jest.fn(() =>
+      Promise.resolve({
+        accessKeyId: "foo",
+        secretAccessKey: "bar",
+        expiration: Date.now() + 600 // expires in ten minutes
+      })
+    );
+    const memoized = memoize(provider);
+
+    expect((await memoized()).accessKeyId).toEqual("foo");
+    expect(provider.mock.calls.length).toBe(1);
+    expect((await memoized()).secretAccessKey).toEqual("bar");
+    expect(provider.mock.calls.length).toBe(1);
+
+    clockMock.mockReset();
+    clockMock.mockReturnValue(601000); // One second past previous expiration
+
+    expect((await memoized()).accessKeyId).toEqual("foo");
+    expect(provider.mock.calls.length).toBe(2);
+    expect((await memoized()).secretAccessKey).toEqual("bar");
+    expect(provider.mock.calls.length).toBe(2);
+  });
+});

packages/credential-provider-base/index.ts

@@ -0,0 +1,5 @@
+export * from "./lib/chain";
+export * from "./lib/CredentialError";
+export * from "./lib/fromCredentials";
+export * from "./lib/isCredentials";
+export * from "./lib/memoize";

packages/credential-provider-base/lib/CredentialError.ts

@@ -0,0 +1,16 @@
+import { chain } from "./chain";
+
+/**
+ * An error representing a failure of an individual credential provider.
+ *
+ * This error class has special meaning to the {@link chain} method. If a
+ * provider in the chain is rejected with an error, the chain will only proceed
+ * to the next provider if the value of the `tryNextLink` property on the error
+ * is truthy. This allows individual providers to halt the chain and also
+ * ensures the chain will stop if an entirely unexpected error is encountered.
+ */
+export class CredentialError extends Error {
+  constructor(message: string, public readonly tryNextLink: boolean = true) {
+    super(message);
+  }
+}

packages/credential-provider-base/lib/chain.ts

@@ -0,0 +1,41 @@
+import { CredentialProvider } from "@aws/types";
+import { CredentialError } from "./CredentialError";
+
+/**
+ * Compose a single credential provider function from multiple credential
+ * providers. The first provider in the argument list will always be invoked;
+ * subsequent providers in the list will be invoked in the order in which the
+ * were received if the preceding provider did not successfully resolve.
+ *
+ * If no providers were received or no provider resolves successfully, the
+ * returned promise will be rejected.
+ */
+export function chain(
+  ...providers: Array<CredentialProvider>
+): CredentialProvider {
+  return () => {
+    providers = providers.slice(0);
+    let provider = providers.shift();
+    if (provider === undefined) {
+      return Promise.reject(
+        new CredentialError("No credential providers in chain")
+      );
+    }
+    let promise = provider();
+    while ((provider = providers.shift())) {
+      promise = promise.catch(
+        (provider => {
+          return (err: CredentialError) => {
+            if (err.tryNextLink) {
+              return provider();
+            }
+
+            throw err;
+          };
+        })(provider)
+      );
+    }
+
+    return promise;
+  };
+}

packages/credential-provider-base/lib/fromCredentials.ts

@@ -0,0 +1,8 @@
+import { CredentialProvider, Credentials } from "@aws/types";
+
+/**
+ * Convert a static credentials object into a credential provider function.
+ */
+export function fromCredentials(credentials: Credentials): CredentialProvider {
+  return () => Promise.resolve(credentials);
+}

packages/credential-provider-base/lib/isCredentials.ts

@@ -0,0 +1,16 @@
+import { Credentials } from "@aws/types";
+
+/**
+ * Evaluate the provided argument and determine if it represents a static
+ * credentials object.
+ */
+export function isCredentials(arg: any): arg is Credentials {
+  return (
+    typeof arg === "object" &&
+    arg !== null &&
+    typeof arg.accessKeyId === "string" &&
+    typeof arg.secretAccessKey === "string" &&
+    ["string", "undefined"].indexOf(typeof arg.sessionToken) > -1 &&
+    ["number", "undefined"].indexOf(typeof arg.expiration) > -1
+  );
+}

packages/credential-provider-base/lib/memoize.ts

@@ -0,0 +1,36 @@
+import { CredentialProvider } from "@aws/types";
+
+/**
+ * Decorates a credential provider with credential-specific memoization. If the
+ * decorated provider returns permanent credentials, it will only be invoked
+ * once; if the decorated provider returns temporary credentials, it will be
+ * invoked again when the validity of the returned credentials is less than 5
+ * minutes.
+ */
+export function memoize(provider: CredentialProvider): CredentialProvider {
+  let result = provider();
+  let isConstant: boolean = false;
+
+  return () => {
+    if (isConstant) {
+      return result;
+    }
+
+    return result.then(credentials => {
+      if (!credentials.expiration) {
+        isConstant = true;
+        return credentials;
+      }
+
+      if (credentials.expiration - 300 > getEpochTs()) {
+        return credentials;
+      }
+
+      return (result = provider());
+    });
+  };
+}
+
+function getEpochTs() {
+  return Math.floor(Date.now() / 1000);
+}

packages/credential-provider-base/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@aws/credential-provider-base",
+  "version": "0.0.1",
+  "private": true,
+  "description": "AWS credential provider shared core",
+  "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "tsc",
+    "pretest": "tsc",
+    "test": "jest"
+  },
+  "keywords": [
+    "aws",
+    "credentials"
+  ],
+  "author": "[email protected]",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@aws/types": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^19.2.2",
+    "jest": "^19.0.2",
+    "typescript": "^2.3"
+  }
+}

packages/credential-provider-base/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es5",
+    "declaration": true,
+    "strict": true,
+    "sourceMap": true,
+    "lib": [
+      "es5",
+      "es2015.promise"
+    ]
+  }
+}