@aws/nx-plugin 0.0.0

package/src/cloudscape-website/app/schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "Cloudscape App",
+  "title": "Create a Cloudscape React Application",
+  "description": "Create a Cloudscape React application for Nx.",
+  "examples": [
+    {
+      "command": "nx g app myapp --directory=myorg",
+      "description": "Generate `apps/myorg/myapp` and `apps/myorg/myapp-e2e`"
+    },
+    {
+      "command": "nx g app myapp --classComponent",
+      "description": "Use class components instead of functional components"
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name of the application.",
+      "type": "string",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the application?",
+      "pattern": "^[a-zA-Z][^:]*$"
+    },
+    "directory": {
+      "description": "The directory of the new application.",
+      "type": "string",
+      "alias": "dir",
+      "x-priority": "important",
+      "default": "packages",
+      "x-prompt": "What directory would you like to store your application in?"
+    },
+    "projectNameAndRootFormat": {
+      "description": "Whether to generate the project name and root directory as provided (`as-provided`) or generate them composing their values and taking the configured layout into account (`derived`).",
+      "type": "string",
+      "enum": ["as-provided", "derived"]
+    },
+    "style": {
+      "description": "The file extension to be used for style files.",
+      "type": "string",
+      "default": "css",
+      "alias": "s",
+      "x-prompt": {
+        "message": "Which stylesheet format would you like to use?",
+        "type": "list",
+        "items": [
+          {
+            "value": "css",
+            "label": "CSS"
+          },
+          {
+            "value": "scss",
+            "label": "SASS(.scss)       [ https://sass-lang.com                     ]"
+          },
+          {
+            "value": "less",
+            "label": "LESS              [ https://lesscss.org                       ]"
+          },
+          {
+            "value": "tailwind",
+            "label": "tailwind [ https://tailwindcss.com/            ]"
+          },
+          {
+            "value": "styled-components",
+            "label": "styled-components [ https://styled-components.com            ]"
+          },
+          {
+            "value": "@emotion/styled",
+            "label": "emotion           [ https://emotion.sh                       ]"
+          },
+          {
+            "value": "styled-jsx",
+            "label": "styled-jsx        [ https://www.npmjs.com/package/styled-jsx ]"
+          },
+          {
+            "value": "none",
+            "label": "None"
+          }
+        ]
+      }
+    },
+    "linter": {
+      "description": "The tool to use for running lint checks.",
+      "type": "string",
+      "enum": ["eslint", "none"],
+      "default": "eslint"
+    },
+    "skipFormat": {
+      "description": "Skip formatting files.",
+      "type": "boolean",
+      "default": false,
+      "x-priority": "internal"
+    },
+    "skipNxJson": {
+      "description": "Skip updating `nx.json` with default options based on values provided to this app.",
+      "type": "boolean",
+      "default": false,
+      "x-priority": "internal"
+    },
+    "unitTestRunner": {
+      "type": "string",
+      "enum": ["jest", "vitest", "none"],
+      "description": "Test runner to use for unit tests.",
+      "x-prompt": "Which unit test runner would you like to use?",
+      "default": "vitest",
+      "x-priority": "important"
+    },
+    "inSourceTests": {
+      "type": "boolean",
+      "default": false,
+      "description": "When using Vitest, separate spec files will not be generated and instead will be included within the source files. Read more on the Vitest docs site: https://vitest.dev/guide/in-source.html"
+    },
+    "tags": {
+      "type": "string",
+      "description": "Add tags to the application (used for linting).",
+      "alias": "t"
+    },
+    "pascalCaseFiles": {
+      "type": "boolean",
+      "description": "Use pascal case component file name (e.g. `App.tsx`).",
+      "alias": "P",
+      "default": false
+    },
+    "classComponent": {
+      "type": "boolean",
+      "description": "Use class components instead of functional component.",
+      "alias": "C",
+      "default": false
+    },
+    "js": {
+      "type": "boolean",
+      "description": "Generate JavaScript files rather than TypeScript files.",
+      "default": false
+    },
+    "globalCss": {
+      "type": "boolean",
+      "description": "Default is `false`. When `true`, the component is generated with `*.css`/`*.scss` instead of `*.module.css`/`*.module.scss`.",
+      "default": false
+    },
+    "strict": {
+      "type": "boolean",
+      "description": "Creates an application with strict mode and strict type checking.",
+      "default": true
+    },
+    "setParserOptionsProject": {
+      "type": "boolean",
+      "description": "Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.",
+      "default": false
+    },
+    "compiler": {
+      "type": "string",
+      "description": "The compiler to use.",
+      "enum": ["babel", "swc"],
+      "default": "swc",
+      "x-priority": "important"
+    },
+    "skipPackageJson": {
+      "description": "Do not add dependencies to `package.json`.",
+      "type": "boolean",
+      "default": false,
+      "x-priority": "internal"
+    },
+    "rootProject": {
+      "description": "Create a application at the root of the workspace",
+      "type": "boolean",
+      "default": false,
+      "hidden": true
+    },
+    "bundler": {
+      "description": "The bundler to use.",
+      "type": "string",
+      "enum": ["vite", "webpack", "rspack"],
+      "x-prompt": "Which bundler do you want to use to build the application?",
+      "default": "vite",
+      "x-priority": "important"
+    },
+    "minimal": {
+      "description": "Generate a React app with a minimal setup, no separate test files.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": ["name"],
+  "examplesFile": "../../../docs/application-examples.md"
+}

package/src/cloudscape-website/cognito-auth/README.md

@@ -0,0 +1,172 @@
+# Cognito Auth Generator
+
+## Overview
+This generator adds AWS Cognito authentication to an existing Cloudscape React application. It sets up the necessary components and infrastructure for user authentication using Amazon Cognito, including sign-in, sign-up, and password recovery flows. The generator integrates seamlessly with the Cloudscape Design System components and configures all required AWS resources through CDK.
+
+## Prerequisites
+
+Before using this generator, ensure your project meets these requirements:
+
+1. The project must have a `main.tsx` file in its source directory
+2. The `main.tsx` file must contain a `<RuntimeConfigProvider>` element
+3. The project must be a valid Cloudscape application
+
+Example of required `main.tsx` structure:
+```typescript
+import { RuntimeConfigProvider } from './components/RuntimeConfig';
+
+const App = () => (
+  <RuntimeConfigProvider>
+    {/* Your app components */}
+  </RuntimeConfigProvider>
+);
+```
+
+If these prerequisites are not met, the generator will fail with an error.
+
+## Usage
+
+You can add Cognito authentication to your Cloudscape website in two ways:
+
+### 1. Using VSCode IDE
+
+First, install the NX Console extension for VSCode:
+1. Open VSCode
+2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
+3. Search for "Nx Console"
+4. Install [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
+
+Then add authentication:
+1. Open the NX Console in VSCode
+2. Click on "Generate"
+3. Search for "cloudscape-website#cognito-auth"
+4. Fill in the required parameters:
+   - project: Your existing Cloudscape application name
+   - allowSignup: Whether to enable self-signup (optional)
+5. Click "Run"
+
+### 2. Using CLI
+
+Add authentication to your existing Cloudscape application:
+```bash
+nx g @aws/nx-plugin:cloudscape-website#cognito-auth --project=my-cloudscape-app
+```
+
+Enable self-signup:
+```bash
+nx g @aws/nx-plugin:cloudscape-website#cognito-auth --project=my-cloudscape-app --allowSignup=true
+```
+
+You can also perform a dry-run to see what files would be generated without actually creating them:
+```bash
+nx g @aws/nx-plugin:cloudscape-website#cognito-auth --project=my-cloudscape-app --dry-run
+```
+
+All methods will add Cognito authentication to your existing Cloudscape website application with all the necessary components and infrastructure code.
+
+## Input Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| project* | string | - | The root directory of the Cloudscape application (required) |
+| allowSignup | boolean | false | Whether to allow self-signup |
+
+*Required parameter
+
+## Expected Output
+
+The generator adds authentication-related components and infrastructure:
+
+### 1. React Components
+```
+<directory>/<project>/
+├── src/
+│   └── components/
+│       └── CognitoAuth/
+│           └── index.tsx         # Main authentication component
+```
+
+### 2. Infrastructure Code
+```
+common/constructs/
+├── src/
+│   └── identity/
+│       ├── index.ts              # Exports for identity constructs
+│       ├── user-identity.ts      # Main identity construct
+│       └── userpool-with-mfa.ts  # User pool configuration
+```
+
+Additionally, it:
+1. Installs required dependencies:
+   - @aws-northstar/ui
+   - aws-cdk-lib
+   - constructs
+   - @aws-cdk/aws-cognito-identitypool-alpha
+2. Updates the application's runtime configuration to include Cognito settings
+3. Automatically integrates the authentication component into your application's main.tsx
+
+## Infrastructure Architecture
+
+```mermaid
+graph TD
+    subgraph AWS Cloud
+        UP[Cognito User Pool] --> IP[Identity Pool]
+        UP --> Client[Web Client]
+        IP --> IAM[IAM Roles]
+    end
+```
+
+The infrastructure stack adds:
+1. **Cognito User Pool**
+   - User directory management
+   - Sign-up and sign-in flows
+   - MFA configuration
+
+2. **Cognito Identity Pool**
+   - Federated identities
+   - AWS credentials mapping
+   - IAM role assignment
+
+3. **Web Client**
+   - User Password and SRP auth flows
+   - Token handling
+
+## Authentication Components
+
+The generator automatically sets up authentication in your application by:
+1. Importing the CognitoAuth component in main.tsx
+2. Wrapping your application with the CognitoAuth component inside the RuntimeConfigProvider
+3. Configuring the authentication UI with:
+   - Sign in form
+   - Sign up form (if enabled)
+   - Password recovery
+   - MFA setup and verification
+
+No manual setup is required as the generator handles all the necessary component integration.
+
+## Runtime Configuration
+
+The generator automatically integrates with the RuntimeConfig system to provide Cognito configuration:
+
+### Infrastructure Usage
+
+```typescript
+import { UserIdentity } from ':my-org/common-constructs';
+import { Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+
+export class MyWebsiteStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    // Create the Cognito authentication resources
+    new UserIdentity(this, 'Identity');
+    
+    // The runtime config is automatically updated with Cognito settings
+  }
+}
+```
+
+### Frontend Usage
+
+The CognitoAuth component automatically uses the runtime configuration.

package/src/cloudscape-website/cognito-auth/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,238 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`cognito-auth generator > should generate files > cognito-auth-component 1`] = `
+"/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+import { CognitoAuth as NorthstarCognitoAuth } from '@aws-northstar/ui';
+import React, { useContext } from 'react';
+import Config from '../../config';
+import { RuntimeConfigContext } from '../RuntimeConfig';
+
+/**
+ * Sets up the Cognito auth.
+ *
+ * This assumes a runtime-config.json file is present at '/'. In order for Auth to be set up automatically,
+ * the runtime-config.json must have the cognitoProps set.
+ */
+const CognitoAuth: React.FC<any> = ({ children }) => {
+  const runtimeConfig = useContext(RuntimeConfigContext);
+
+  return runtimeConfig?.cognitoProps ? (
+    <NorthstarCognitoAuth
+      header={Config.applicationName}
+      userPoolId={runtimeConfig.cognitoProps.userPoolId}
+      clientId={runtimeConfig.cognitoProps.userPoolWebClientId}
+      region={runtimeConfig.cognitoProps.region}
+      identityPoolId={runtimeConfig.cognitoProps.identityPoolId}
+      allowSignup={true}
+      signUpAttributes={[
+        {
+          displayName: 'Email',
+          name: 'email',
+          required: true,
+        },
+        {
+          displayName: 'Given name',
+          name: 'given_name',
+          required: true,
+        },
+        {
+          displayName: 'Last name',
+          name: 'family_name',
+          required: true,
+        },
+      ]}
+    >
+      {children}
+    </NorthstarCognitoAuth>
+  ) : (
+    <></>
+  );
+};
+
+export default CognitoAuth;
+"
+`;
+
+exports[`cognito-auth generator > should generate files > identity-index 1`] = `
+"/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+export * from './user-identity.js';
+export * from './userpool-with-mfa.js';
+"
+`;
+
+exports[`cognito-auth generator > should generate files > user-identity 1`] = `
+"/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+import {
+  IdentityPool,
+  UserPoolAuthenticationProvider,
+} from '@aws-cdk/aws-cognito-identitypool-alpha';
+import { CfnOutput, Stack } from 'aws-cdk-lib';
+import { UserPool, UserPoolClient } from 'aws-cdk-lib/aws-cognito';
+import { Construct } from 'constructs';
+import { UserPoolWithMfa } from './userpool-with-mfa.js';
+import { RuntimeConfig } from '../runtime-config/index.js';
+
+const WEB_CLIENT_ID = 'WebClient';
+
+/**
+ * Creates a UserPool and Identity Pool with sane defaults configured intended for usage from a web client.
+ */
+export class UserIdentity extends Construct {
+  public readonly identityPool: IdentityPool;
+  public readonly userPool: UserPool;
+  public readonly userPoolClient: UserPoolClient;
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    // Unless explicitly stated, created a default Cognito User Pool and Web Client.
+    this.userPool = new UserPoolWithMfa(this, 'UserPool');
+
+    this.identityPool = new IdentityPool(this, 'IdentityPool');
+
+    const existingClient = this.userPool.node.children.find(
+      (e) => e.node.id === WEB_CLIENT_ID && e instanceof UserPoolClient
+    ) as UserPoolClient | undefined;
+
+    this.userPoolClient =
+      existingClient ??
+      this.userPool.addClient(WEB_CLIENT_ID, {
+        authFlows: {
+          userPassword: true,
+          userSrp: true,
+        },
+      });
+
+    this.identityPool.addUserPoolAuthentication(
+      new UserPoolAuthenticationProvider({
+        userPool: this.userPool,
+        userPoolClient: this.userPoolClient,
+      })
+    );
+
+    new CfnOutput(this, \`\${id}-UserPoolId\`, {
+      value: this.userPool.userPoolId,
+    });
+
+    new CfnOutput(this, \`\${id}-IdentityPoolId\`, {
+      value: this.identityPool.identityPoolId,
+    });
+
+    RuntimeConfig.ensure(this).config.cognitoProps = {
+      region: Stack.of(this).region,
+      identityPoolId: this.identityPool.identityPoolId,
+      userPoolId: this.userPool?.userPoolId,
+      userPoolWebClientId: this.userPoolClient?.userPoolClientId,
+    };
+  }
+}
+"
+`;
+
+exports[`cognito-auth generator > should generate files > userpool-with-mfa 1`] = `
+"/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+import { PDKNag } from '@aws/pdk/pdk-nag';
+import { Duration, Stack } from 'aws-cdk-lib';
+import {
+  AccountRecovery,
+  AdvancedSecurityMode,
+  Mfa,
+  UserPool,
+} from 'aws-cdk-lib/aws-cognito';
+import { Construct } from 'constructs';
+
+/**
+ * Configures a UserPool with MFA across SMS/TOTP using sane defaults.
+ */
+export class UserPoolWithMfa extends UserPool {
+  constructor(scope: Construct, id: string) {
+    super(scope, id, {
+      deletionProtection: true,
+      passwordPolicy: {
+        minLength: 8,
+        requireLowercase: true,
+        requireUppercase: true,
+        requireDigits: true,
+        requireSymbols: true,
+        tempPasswordValidity: Duration.days(3),
+      },
+      mfa: Mfa.REQUIRED,
+      mfaSecondFactor: { sms: true, otp: true },
+      signInCaseSensitive: false,
+      advancedSecurityMode: AdvancedSecurityMode.ENFORCED,
+      signInAliases: { username: true, email: true },
+      accountRecovery: AccountRecovery.EMAIL_ONLY,
+      selfSignUpEnabled: true,
+      standardAttributes: {
+        phoneNumber: { required: false },
+        email: { required: true },
+        givenName: { required: true },
+        familyName: { required: true },
+      },
+      autoVerify: {
+        email: true,
+        phone: true,
+      },
+      keepOriginal: {
+        email: true,
+        phone: true,
+      },
+    });
+
+    const stack = Stack.of(this);
+
+    ['AwsSolutions-IAM5', 'AwsPrototyping-IAMNoWildcardPermissions'].forEach(
+      (RuleId) => {
+        PDKNag.addResourceSuppressionsByPathNoThrow(
+          stack,
+          \`\${PDKNag.getStackPrefix(stack)}\${id}/UserPool/smsRole/Resource\`,
+          [
+            {
+              id: RuleId,
+              reason:
+                'MFA requires sending a text to a users phone number which cannot be known at deployment time.',
+              appliesTo: ['Resource::*'],
+            },
+          ]
+        );
+      }
+    );
+  }
+}
+"
+`;
+
+exports[`cognito-auth generator > should handle main.tsx without RuntimeConfigProvider 1`] = `[Error: Could not locate the BrowserRouter element in main.tsx]`;
+
+exports[`cognito-auth generator > should handle missing main.tsx 1`] = `[Error: Can only run this generator on a project which contains packages/test-project/src/main.tsx]`;
+
+exports[`cognito-auth generator > should not be able to run the generator multiple times 1`] = `[Error: This generator has already been run on test-project.]`;
+
+exports[`cognito-auth generator > should update main.tsx when RuntimeConfigProvider exists > main-tsx-with-runtime-config 1`] = `
+"import CognitoAuth from './components/CognitoAuth';
+import RuntimeConfigProvider from './components/RuntimeConfig';
+import { RuntimeConfigProvider } from './components/RuntimeConfig';
+import { BrowserRouter } from 'react-router-dom';
+export function App() {
+  return (
+    <RuntimeConfigProvider>
+      <CognitoAuth>
+        <RuntimeConfigProvider>
+          <BrowserRouter>Hello World</BrowserRouter>
+        </RuntimeConfigProvider>
+      </CognitoAuth>
+    </RuntimeConfigProvider>
+  );
+}
+"
+`;
+
+exports[`cognito-auth generator > should update shared constructs index.ts > common/constructs-index 1`] = `
+"export * from './identity/index.js';
+export * from './runtime-config/index.js';
+"
+`;

package/src/cloudscape-website/cognito-auth/files/app/components/CognitoAuth/index.tsx.template

@@ -0,0 +1,50 @@
+/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+import { CognitoAuth as NorthstarCognitoAuth } from "@aws-northstar/ui";
+import React, { useContext } from "react";
+import Config from "../../config";
+import { RuntimeConfigContext } from "../RuntimeConfig";
+
+/**
+ * Sets up the Cognito auth.
+ *
+ * This assumes a runtime-config.json file is present at '/'. In order for Auth to be set up automatically,
+ * the runtime-config.json must have the cognitoProps set.
+ */
+const CognitoAuth: React.FC<any> = ({ children }) => {
+  const runtimeConfig = useContext(RuntimeConfigContext);
+
+  return runtimeConfig?.cognitoProps ? (
+    <NorthstarCognitoAuth
+      header={Config.applicationName}
+      userPoolId={runtimeConfig.cognitoProps.userPoolId}
+      clientId={runtimeConfig.cognitoProps.userPoolWebClientId}
+      region={runtimeConfig.cognitoProps.region}
+      identityPoolId={runtimeConfig.cognitoProps.identityPoolId}
+      <%if (allowSignup) {%>allowSignup={true}<% } %>
+      signUpAttributes={[
+        {
+            displayName: "Email",
+            name: "email",
+            required: true,
+        },
+        {
+            displayName: "Given name",
+            name: "given_name",
+            required: true,
+        },
+        {
+            displayName: "Last name",
+            name: "family_name",
+            required: true,
+        }
+      ]}
+    >
+      {children}
+    </NorthstarCognitoAuth>
+  ) : (
+    <></>
+  );
+};
+
+export default CognitoAuth;

package/src/cloudscape-website/cognito-auth/files/common/constructs/src/identity/index.ts.template

@@ -0,0 +1,4 @@
+/*! Copyright [Amazon.com](http://amazon.com/), Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0 */
+export * from "./user-identity.js";
+export * from "./userpool-with-mfa.js";