much more user friendly info in demo app (#184)

* much more user friendly info in demo app * clean up backend docs, especially around signing key stuff * Further refinement of the text on this page. Tried to break up the repetition across the examples, and add some extra resources to the home page. * clean up some demo app writing and fix demo app favicon and title * little bit more writing clean up in demo app * nit * clean up hacking sentence Co-authored-by: Free Wortley <[email protected]> Former-commit-id: 71770ce Former-commit-id: 0d39819843a08a18ef429a85c28897ae9f80c41b
lunasec-io · Oct 27, 2021 · 2500a5e · 2500a5e
1 parent 7719f2c
commit 2500a5e
Show file tree

Hide file tree

Showing 16 changed files with 280 additions and 47 deletions.
diff --git a/docs/package.json b/docs/package.json
@@ -12,7 +12,6 @@
     "swizzle": "docusaurus swizzle",
     "deploy": "yarn run openapi:generate &&  docusaurus deploy",
     "clear": "docusaurus clear",
-    "serve": "yarn run openapi:generate && yarn build && docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "openapi:generate": "redoc-cli bundle ../api-spec/schema/full-tokenizer.yaml --output static/tokenizer-api-spec-static/index.html"

diff --git a/docs/pages/deployment/_category_.yml b/docs/pages/deployment/_category_.yml
@@ -0,0 +1,2 @@
+label: Deployment
+position: 3
diff --git a/...d/dedicated-tokenizer/secret-providers.md → docs/pages/deployment/secret-providers.md b/...d/dedicated-tokenizer/secret-providers.md → docs/pages/deployment/secret-providers.md
@@ -2,7 +2,7 @@
 id: "secret-providers"
 title: "Secret Providers"
 sidebar_label: "Secret Providers"
-sidebar_position: 7
+sidebar_position: 2
 ---
 <!--
   ~ Copyright by LunaSec (owned by Refinery Labs, Inc)
@@ -19,11 +19,12 @@ sidebar_position: 7
 -->
 # Available Secret Providers
 
-LunaSec currently supports the following secret providers:
+When we set up the LunaSec Node SDK, we pass a private key that LunaSec uses to establish trust with your app.
+LunaSec provides a few different ways to set it:
 
 ## Manual
 
-Provide a `'<siging key>'` as a `KeyLike` value.
+Provide a `'<signing key>'` as a `KeyLike` value.
 
 ```typescript
 import { createPrivateKey } from 'crypto';
@@ -32,15 +33,15 @@ export const lunaSec = new LunaSec({
   auth: {
     secrets: {
       provider: 'manual',
-      signingKey: createPrivateKey('<signing key>')
+      signingKey: createPrivateKey('PRIVATEKEY123ABC')
     },
   }
 });
 ```
 
 ## Environment Variable
 
-Set the environment variable `LUNASEC_SIGING_KEY` which will be detected by LunaSec at runtime.
+Set the environment variable `LUNASEC_SIGNING_KEY` which will be detected by LunaSec at runtime.
 
 ```typescript
 export const lunaSec = new LunaSec({

diff --git a/docs/pages/getting-started/dedicated-tokenizer/backend.md b/docs/pages/getting-started/dedicated-tokenizer/backend.md
@@ -26,6 +26,7 @@ Install the module:
 yarn add @lunasec/node-sdk
 ```
 ### Configuration
+Here's an example configuration, below we will explain what the values mean:  
 ```typescript
 import { LunaSec } from '@lunasec/node-sdk'
 export const lunaSec = new LunaSec({
@@ -39,6 +40,8 @@ export const lunaSec = new LunaSec({
     },
 });
 ```
+
+#### Session ID Provider
 The session ID provider callback might look like this:
 ```typescript
 export function lunaSecSessionIdProvider(req: Request): Promise<string | null> {
@@ -51,26 +54,30 @@ export function lunaSecSessionIdProvider(req: Request): Promise<string | null> {
   });
 }
 ```
+#### Secret Signing Key
+When we set up the LunaSec Node SDK, we pass a private key that LunaSec uses to establish trust with your app.
+
+If the `environment` secret provider is used (as shown above), the `LUNASEC_SIGNING_KEY` environment
+variable must be set with a valid RSA key, base64 encoded. 
+
+Here is an example of how you would generate a secret key to use for this on arch linux:
+```shell
+ssh-keygen -t rsa -f lunasec_signing_key
+cat lunasec_signing_key | base64 -w0
+```
+
+LunaSec also supports passing a secret key directly or reading one from AWS Secrets manager.
+For instructions, see [the secret provider page](/pages/deployment/secret-providers) of the deployment documentation.
 
 :::tip
-To see full documentation of the LunaSec class and the configuration it takes, see the [NodeSDK typedoc](/pages/node-sdk/classes/LunaSec/).
+To see full documentation of the configuration, see the [config's typedoc](/pages/node-sdk/interfaces/LunaSecConfig/).  To 
+see commented typedoc for everything this class exposes, see the [typedoc for the class](/pages/node-sdk/classes/LunaSec/).
 :::
 
 Now the SDK is configured and you have access to its modules, like the auth plugin: 
 
 ### Registering the auth plugin with express
 
-The LunaSec auth plugin uses a provided signing key to create sessions for the Tokenizer Backend. If the 
-`environment` secret provider is used (as is shown above in the lunasec configuration), the `LUNASEC_SIGNING_KEY` environment
-variable must be set with a valid RSA key. LunaSec supports other secret providers, and a guide for this can be found [here](./secret-providers.md).
-
-```shell
-$ ssh-keygen -t rsa -f lunasec_signing_key
-$ cat lunasec_signing_key | base64 -w0
-  <encoded signing key>
-```
-
-Your backend should have the environment variable `LUNASEC_SIGNING_KEY` set to the `<encoded signing key>`.
 
 If you want to use your own session management or use a tool like Passport, register the auth plugin with express. This will transfer the session information
 onto the domain that the Dedicated Tokenizer will run on.

diff --git a/docs/pages/getting-started/dedicated-tokenizer/securing-text.md b/docs/pages/getting-started/dedicated-tokenizer/securing-text.md
@@ -21,7 +21,7 @@ sidebar_position: 5
 As you follow along with this guide, you can check the custom properties each component supports(and what those properties do)
 in the [type documentation](/pages/react-sdk/interfaces/SecurePropsLookup).
 ::::
-# Secure Forms
+## Secure Forms
 
 Let's create a form secured with LunaSec.  Here is a simple scenario where we want to tokenize a Social Security Number.
 ```tsx
@@ -42,6 +42,10 @@ them easy to use and interoperable with other DOM libraries.
 For example, `<SecureInput>` calls `onChange` and `onBlur` event handlers just like the native `<input>` element.  For the most part, they can be styled
 just like native elements and will allow you to build forms and pages as you normally would, with a few exceptions.
 
+:::tip
+The secure input we created shouldn't change how the app looks at all(that's the point) but if we right-click and
+inspect it we can see the cross-domain iFrame that LunaSec creates to protect your data.
+:::
 Creating a Text Area for multi-line data entry is pretty similar, this time let's give it some custom styling:
 ```tsx
 // ... inside secure form
@@ -59,11 +63,11 @@ Creating a Text Area for multi-line data entry is pretty similar, this time let'
 :::note
 `<SecureInput>` and `<SecureTextArea>` need to be inside a `<SecureForm>` because it captures submit events and tells them
 to tokenize their plaintext.
-`<SecureForm>` will wait to fire your `onSubmit` handler until they are done.  Note that normal submit methods like a submit button and 
-hitting `enter` work fine.
+`<SecureForm>` will wait to fire your `onSubmit` handler until they are done tokenizing.  Note that normal submit methods like a submit button and 
+hitting `enter` in a text box work fine.
 :::
 
-# Displaying Secure Data
+## Displaying Secure Data
 The `<SecureParagraph` element can take a token and display it as text.  
 ```tsx
 <SecureParagraph 
@@ -75,7 +79,7 @@ The major caveat here is that the text can't be displayed inline because we can'
 secured data to the surrounding page.  It's a good idea to style this element large enough to display the text it's 
 going to display.
 
-# Advanced Form Usage
+## Advanced Form Usage
 
 SecureInput supports many options and can be used with component libraries. 
 
@@ -101,8 +105,6 @@ Inputs come with support for all the normal input types such as `email` and `pas
 prefilling the field with some previously created secure data.  You can choose from one of several pre-made validators if you need
 basic validation.
 
-For a full list of the available options, see THE TYPEDOC LINK HERE.
-
 :::note Special Cases
 Some things you would normally do may need to be done differently or may not be possible because your page
 just doesn't have access to the plaintext value.  An example of this is validations, where you have to use one of our pre-made validators.

diff --git a/docs/pages/overview/features.md b/docs/pages/overview/features.md
@@ -36,7 +36,7 @@ Your data is protected against Cross-Site Scripting(XSS), and the parts of the a
 The `react-sdk` provides a suite of "Secure Form" components that follow this pattern. 
 Onboarding is simply replacing your `<form>` and `<input>` elements with drop-in replacement components which handle creating and communicating with the iFrame.
 Your styling and most other DOM features 
-will continue to work normally, even though the element is new securely isolated.  It even works with MaterialUi 
+will continue to work normally, even though the element is now securely isolated.  It even works with MaterialUi 
 and other component libraries.
 
 ### Secure Function

diff --git a/favicon.png b/favicon.png
diff --git a/js/demo-apps/packages/react-front-end/public/favicon.ico b/js/demo-apps/packages/react-front-end/public/favicon.ico
diff --git a/js/demo-apps/packages/react-front-end/public/favicon.png b/js/demo-apps/packages/react-front-end/public/favicon.png
diff --git a/js/demo-apps/packages/react-front-end/public/index.html b/js/demo-apps/packages/react-front-end/public/index.html
@@ -8,7 +8,7 @@
 
     <meta
       name="description"
-      content="Web site created using create-react-app"
+      content="LunaSec Demo App"
     />
     <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
     <!--
@@ -25,7 +25,7 @@
       work correctly both with client-side routing and a non-root public URL.
       Learn how to configure a non-root public URL by running `npm run build`.
     -->
-    <title>React App</title>
+    <title>LunaSec Demo</title>
   </head>
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>

diff --git a/js/demo-apps/packages/react-front-end/src/common/components/Home.tsx b/js/demo-apps/packages/react-front-end/src/common/components/Home.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react/jsx-no-target-blank */
 /*
  * Copyright 2021 by LunaSec (owned by Refinery Labs, Inc)
  *
@@ -14,11 +15,7 @@
  * limitations under the License.
  *
  */
-import { makeStyles } from '@material-ui/core';
-import Card from '@material-ui/core/Card';
-import CardContent from '@material-ui/core/CardContent';
-import Grid from '@material-ui/core/Grid';
-import Typography from '@material-ui/core/Typography';
+import { Box, Card, CardContent, CardHeader, Divider, Grid, makeStyles, Typography } from '@material-ui/core';
 import React from 'react';
 
 import logo from '../../static/logo.svg';
@@ -41,9 +38,133 @@ export const Home: React.FunctionComponent = () => {
           <Typography>
             This is a fully functional application which uses LunaSec to protect its sensitive data.
           </Typography>
-          <hr />
+          <br />
           <Typography>
-            You can login to is this site with the credentials - username: <b>test</b> password: <b>test</b>
+            It looks and functions like any other web app, but many of the fields have been secured with LunaSec. Under
+            the hood, LunaSec is keeping the data secure. To set up LunaSec in your own application, see the{' '}
+            <a
+              href="https://www.lunasec.io/docs/pages/getting-started/dedicated-tokenizer/introduction/"
+              target="_blank"
+              rel="prefetch"
+            >
+              Getting Started Guide.
+            </a>
+          </Typography>
+        </CardContent>
+      </Card>
+      <br />
+      <Card>
+        <CardHeader title="Getting Started" />
+        <Divider />
+        <CardContent>
+          <Typography>
+            Before trying the LunaSec Secure Elements, you must first login to the site by using the links on the left.
+            A test user has been created for you to login with.
+            <h4>Login Credentials:</h4>
+            <ul>
+              <li>
+                Username: <b>test</b>
+              </li>
+              <li>
+                Password: <b>test</b>
+              </li>
+            </ul>
+            <p>
+              You may also register a new user with any username and password. Once you&apos;ve logged in, you will see
+              a list of elements on the left that you can try in order to explore the app.
+            </p>
+            <Divider />
+            <p>
+              Selecting from a mode with the buttons in the header will switch between different demos. Each demo runs
+              with a different backend service and provides a reference for the different ways that you can integrate
+              LunaSec into your stack.
+            </p>
+            <Divider />
+            <p>
+              <h4>See LunaSec in Action</h4>
+              <p>
+                LunaSec elements are designed to look like normal elements. You will need to dig deeper to see it
+                working:
+              </p>
+              <ul>
+                <li>Use your browser&apos;s Dev Tools to inspect the input elements in the example pages.</li>
+                <li>
+                  Look at the network traffic to see the communication with the Tokenizer Backend and local AWS S3
+                  bucket to store encrypted data.
+                </li>
+                <li>
+                  Review the{' '}
+                  <a
+                    href="https://github.com/lunasec-io/lunasec/tree/master/js/demo-apps/packages"
+                    target="_blank"
+                    rel="prefetch"
+                  >
+                    source code
+                  </a>{' '}
+                  behind this app to start understanding how it works.
+                </li>
+                <li>
+                  Simulate an attack by trying to leak the sensitive data in the examples. Injecting Javascript into the
+                  page should not reveal any sensitive data from the secure fields.
+                </li>
+              </ul>
+            </p>
+          </Typography>
+        </CardContent>
+      </Card>
+      <br />
+      <Card>
+        <CardHeader title="Resources" />
+        <Divider />
+        <CardContent>
+          <Typography>
+            <Box mt={-2}>
+              <h3>Documentation Links</h3>
+            </Box>
+            <ul>
+              <li>
+                <b>
+                  <a href="https://www.lunasec.io/docs/pages/overview/introduction/" target="_blank" rel="prefetch">
+                    Main Documentation
+                  </a>
+                  :
+                </b>{' '}
+                This is the general documentation and is a helpful place to get started with LunaSec.
+              </li>
+
+              <li>
+                <b>
+                  <a
+                    href="https://www.lunasec.io/docs/pages/getting-started/dedicated-tokenizer/introduction/"
+                    target="_blank"
+                    rel="prefetch"
+                  >
+                    Getting Started Guide
+                  </a>
+                  :
+                </b>{' '}
+                A specific guide for setting up the Secure Components in your own application.
+              </li>
+
+              <li>
+                <b>
+                  <a
+                    href="https://www.lunasec.io/docs/pages/overview/demo-app/walkthrough/"
+                    target="_blank"
+                    rel="prefetch"
+                  >
+                    Demo App Walkthrough
+                  </a>
+                  :
+                </b>{' '}
+                An overview of this Demo App, how to use it, and a walkthrough of architecture (with links to the source
+                code).
+              </li>
+            </ul>
+            <p>
+              Thank you for trying LunaSec. For professional support,{' '}
+              <a href="https://www.lunasec.io/contact"> contact us</a>.
+            </p>
           </Typography>
         </CardContent>
       </Card>

diff --git a/...s/packages/react-front-end/src/common/components/secure-components/SecureDownloadDemo.tsx b/...s/packages/react-front-end/src/common/components/secure-components/SecureDownloadDemo.tsx
@@ -15,7 +15,7 @@
  *
  */
 import { SecureDownload } from '@lunasec/react-sdk';
-import { Card, CardContent, CardHeader, Grid, Typography } from '@material-ui/core';
+import { Card, CardContent, CardHeader, Divider, Grid, Typography } from '@material-ui/core';
 import { Alert, AlertTitle } from '@material-ui/lab';
 import React, { useEffect, useState } from 'react';
 
@@ -73,10 +73,26 @@ export const SecureDownloadDemo: React.FunctionComponent = () => {
     <Grid item xs={12}>
       {renderErrors()}
       <Card>
-        <CardHeader
-          title={`Securely Download the last file Uploaded in SecureUpload ${documents[documents.length - 1]}`}
-        />
+        <CardHeader title={`Secure Download Demo`} />
         <CardContent>
+          <p>
+            This download link downloads the last file uploaded to Secure Upload in the previous demo. If you right
+            click and inspect the element with your Developer Tools, you will see that it is actually inside of an
+            iFrame. Even the file name is protected by LunaSec.
+          </p>
+          <p>
+            To see how to set up your own Secure Download,{' '}
+            <a
+              href={
+                'https://www.lunasec.io/docs/pages/getting-started/dedicated-tokenizer/handling-files/#downloading-a-file'
+              }
+            >
+              see here
+            </a>
+            .
+          </p>
+          <Divider />
+          <br />
           <Typography>Download Link:</Typography>
           <SecureDownload token={documents[documents.length - 1]} errorHandler={(e) => setError(e.message)} />
         </CardContent>