feat: add support for secrets

.eslintrc.js

@@ -4,7 +4,15 @@ const { overrides } = require('@netlify/eslint-config-node')
 
 module.exports = {
   extends: '@netlify/eslint-config-node',
-  rules: {},
+  // TODO: remove after https://github.com/netlify/eslint-config-node/pull/230 is merged and released
+  rules: {
+    'node/no-unsupported-features/es-syntax': [
+      'error',
+      {
+        ignores: ['modules'],
+      },
+    ],
+  },
   overrides: [
     ...overrides,
     {
@@ -14,5 +22,16 @@ module.exports = {
         'promise/prefer-await-to-callbacks': 'off',
       },
     },
+    // TODO: remove after https://github.com/netlify/eslint-config-node/pull/230 is merged and released
+    {
+      files: ['*.ts'],
+      extends: ['plugin:@typescript-eslint/recommended', 'plugin:import/typescript'],
+    },
   ],
+  settings: {
+    // TODO: remove after https://github.com/netlify/eslint-config-node/pull/230 is merged and released
+    'import/parsers': {
+      '@typescript-eslint/parser': ['.ts', '.tsx'],
+    },
+  },
 }

README.md

@@ -74,6 +74,105 @@ The following types are exported:
 - `HandlerEvent`
 - `HandlerResponse`
 
+
+## Auth Token Manager
+
+**Note: This feature is currently in beta under Netlify Labs**
+
+To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by [OneGraph](https://www.onegraph.com). It’s enabled on a per-site basis under [Netlify labs](https://app.netlify.com/user/labs) tab, where you can use the Netlify UI to select which services you want to make available for your functions or site builds, and which scopes you need access to. 
+
+### Usage
+
+After you’ve enabled one or more services, you can access the relevant API tokens and secrets in your serverless functions with the `getSecrets` function exported from the `@netlify/functions` package.
+
+> `getSecrets` is fully typed, so you’ll have in-editor autocomplete to explore everything that’s available, and to be confident that you’re handling all of the edge cases
+
+  ```js
+  import { getSecrets } from '@netlify/functions';
+  import { Octokit } from '@octokit/rest';
+
+  export async function handler(event) {
+    // check for a owner/org and repo name in the query params
+    const { owner = 'netlify', repo = 'functions' } = event.queryStringParameters;
+
+    // load the secrets enabled via Netlify Auth Management
+    const secrets = await getSecrets();
+
+    // ensure that GitHub auth is enabled for this site
+    if (!secrets.gitHub?.bearerToken) {
+      return {
+        statusCode: 412,
+        body: JSON.stringify({
+          error:
+            'You must enable GitHub auth in your Netlify dashboard: https://app.netlify.com/user/labs',
+        }),
+      };
+    }
+
+    // use Octokit with the GitHub secret
+    const octokit = new Octokit({ auth: secrets.gitHub.bearerToken });
+
+    // get a list of all issues assigned to the current user
+    const result = await octokit.repos.get({ owner, repo });
+
+    return {
+      statusCode: 200,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(result.data),
+    };
+  }
+  ```
+
+### Checking additional metadata about auth token in your functions and site builds
+Auth Token Manager also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example:
+
+  ```js
+    import { getSecrets } from "@netlify/functions";
+
+    export const handler = async (event) => {
+      // Handle all fetching, refreshing, rotating, etc. of tokens
+      const secrets = await getSecrets();
+
+      // We know that we need either "public_repo" or "repo" scopes granted
+      // in order to run this function properly
+      const sufficientScopes = ["public_repo", "repo"];
+
+      // Secrets have an optional `grantedScopes` field that has details
+      // on what the auth is allowed to do
+      const tokenHasScope = secrets.gitHub.grantedScopes?.some((grantedScope) =>
+        sufficientScopes.includes(grantedScope.scope)
+      );
+
+      // Notice how we can leave a great error message that tells us exactly what
+      // we need to do to fix things.
+      if (!tokenHasScope) {
+        return {
+          statusCode: 412,
+          body: JSON.stringify({
+            error: `You have enabled GitHub auth in your Netlify Auth dashboard, but it's missing a required scope. The auth must have one (or both) of the scopes: ${sufficientScopes.join(", ")}`,
+          }),
+          headers: {
+            "Content-Type": "application/json",
+          },
+        };
+      }
+
+     // ...
+    }
+  ```
+
+### Accessing integration auth tokens during development
+
+When running your site under `netlify dev`, the environmental variables that power the auth management will be synced, and you can transparently develop against the third party APIs - no additional configuration necessary!
+
+### Updating or removing auth tokens from your site
+
+At any time you can revisit the Auth Token Manager tab for your site in [Netlify Labs](https://app.netlify.com/user/labs) (select your team, then select your profile avatar, then Netlify Labs) to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions and site builds _instantly_.
+
+You can also install new services or remove currently-installed services you’re no longer using.
+
 ## Contributors
 
 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to set up and work on this repository. Thanks