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,70 @@
+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,57 @@
+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,38 @@
+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,39 @@
+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,10 @@
+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);
+}