Refactor Cosmetology License schema to remove NPI / require license number (#1291)

The Cosmetology compact does not collect npi in their license records,
and they intend to require all license records to include a license
number as they will use this to search for particular practitioners in
the system. This updates the schemas in the Cosmetology API to remove
reference to npi and enforce the inclusion of the licenseNumber field
with every license upload

The Cosmetology API will be called by the same UI as the original
compact connect app used by JCC. As such,
we needed to set the explicit ui domain in the env context so we set the
correct callback urls, CORS allowed origins, and
email template links. This adds that needed change so that CSV license
uploads through the app will work correctly.

This PR also removes API endpoints for features that will not be
applicable to the Cosmetology compact. This includes endpoints for
programmatically reading privileges from the system, as well as the
search endpoint for exporting privilege CSV reports.

### Requirements List
- The CDK environment contexts in SSM parameter store need to be updated
to include the new optional 'ui_domain_name_override' field (Complete)

### Description List
- Remove NPI from Cosmetology license schema
- Enforce 'licenseNumber' field
- Remove unneeded State API endpoints for programmatically reading data
from the system
- Remove irrelevant endpoint for exporting privilege records through
search API
- Add 'ui_domain_name_override' field to SSM environment contexts

### Testing List
- For API configuration changes: CDK tests added/updated in
`backend/compact-connect/tests/unit/test_api.py`
- For API endpoint changes: OpenAPI spec updated to show latest endpoint
configuration `run compact-connect/bin/download_oas30.py`
- Tests updated to remove reference to NPI and expect licenseNumber
- Code review

Closes #1290 #1283 


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Per-environment UI domain override; custom UI domains now require TLS
1.2. Pipeline stages disable the public execute-api endpoint.

* **Breaking Changes**
* Privilege export/history/deactivation features removed across APIs,
handlers, tests, and docs.
* National Provider Identifier (NPI) removed from
inputs/responses/tests.
* licenseNumber is now required for license submissions;
privilegeJurisdictions and related fields removed.

* **Documentation**
* Added UI domain override guidance; removed signature-auth and
privilege-export documentation and examples.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: landonshumway-ia

backend/common-cdk/common_constructs/stack.py

@@ -97,6 +97,14 @@ def __init__(self, *args, environment_context: dict, environment_name: str, **kw
 
         self.environment_context = environment_context
         self.environment_name = environment_name
+
+        # Guard: all pipeline environments (test, beta, prod) MUST have a domain_name configured
+        if environment_name in ('test', 'beta', 'prod') and not environment_context.get('domain_name'):
+            raise ValueError(
+                f"Pipeline environments (test, beta, prod) require 'domain_name' to be configured. "
+                f"Environment '{environment_name}' is missing this required configuration."
+            )
+
         # We only set the API_BASE_URL common env var if the API_DOMAIN_NAME is set
         # The API_BASE_URL is used by the feature flag client to call the flag check endpoint
         if self.api_domain_name:
@@ -130,14 +138,20 @@ def search_api_domain_name(self) -> str | None:
 
     @property
     def ui_domain_name(self) -> str | None:
+        # Allow explicit override via environment context for cases where the UI is hosted
+        # on a different domain than the backend's hosted zone (e.g. cosmetology backend uses
+        # cosmetology.compactconnect.org but the UI is at app.compactconnect.org)
+        override = self.environment_context.get('ui_domain_name_override')
+        if override is not None:
+            return override
         if self.hosted_zone is not None:
             return f'app.{self.hosted_zone.zone_name}'
         return None
 
     @property
     def allowed_origins(self) -> list[str]:
         allowed_origins = []
-        if self.hosted_zone is not None:
+        if self.ui_domain_name is not None:
             allowed_origins.append(f'https://{self.ui_domain_name}')
 
         if self.environment_context.get('allow_local_ui', False):

backend/compact-connect/common_constructs/cc_api.py

@@ -17,6 +17,7 @@
     MethodLoggingLevel,
     ResponseType,
     RestApi,
+    SecurityPolicy,
     StageOptions,
 )
 from aws_cdk.aws_certificatemanager import Certificate, CertificateValidation
@@ -89,7 +90,14 @@ def __init__(
                 validation=CertificateValidation.from_dns(hosted_zone=stack.hosted_zone),
                 subject_alternative_names=[stack.hosted_zone.zone_name],
             )
-            domain_kwargs = {'domain_name': DomainNameOptions(certificate=certificate, domain_name=domain_name)}
+            domain_kwargs = {
+                'domain_name': DomainNameOptions(
+                    certificate=certificate,
+                    domain_name=domain_name,
+                    # this resource defaults to TLS_1_2, but we will explicitly set this anyway
+                    security_policy=SecurityPolicy.TLS_1_2,
+                )
+            }
 
         access_log_group = LogGroup(scope, 'ApiAccessLogGroup', retention=RetentionDays.ONE_MONTH)
         NagSuppressions.add_resource_suppressions(
@@ -103,10 +111,14 @@ def __init__(
             ],
         )
 
+        # Disable the default execute-api endpoint for all pipeline environments so traffic must use the custom domain.
+        disable_execute_api_endpoint = environment_name in ('test', 'beta', 'prod')
+
         super().__init__(
             scope,
             construct_id,
             cloud_watch_role=True,
+            disable_execute_api_endpoint=disable_execute_api_endpoint,
             deploy_options=StageOptions(
                 # NOTE: If we are ever updating our pipeline architecture which requires a change to the pipeline stack
                 # name, the domain base path mapping for the API will fail to deploy unless we change the name of the

backend/compact-connect/lambdas/nodejs/package.json

@@ -3,6 +3,9 @@
   "version": "1.0.0",
   "type": "commonjs",
   "description": "NodeJS lambdas for Compact Connect",
+  "resolutions": {
+    "fast-xml-parser": "5.3.6"
+  },
   "scripts": {
     "build": "tsc",
     "watch": "tsc -w",

backend/compact-connect/lambdas/nodejs/yarn.lock

@@ -3453,12 +3453,12 @@ fast-levenshtein@^2.0.6:
   resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917"
   integrity sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==
 
-fast-xml-parser@5.3.4:
-  version "5.3.4"
-  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-5.3.4.tgz#06f39aafffdbc97bef0321e626c7ddd06a043ecf"
-  integrity sha512-EFd6afGmXlCx8H8WTZHhAoDaWaGyuIBoZJ2mknrNxug+aZKjkp0a0dlars9Izl+jF+7Gu1/5f/2h68cQpe0IiA==
+fast-xml-parser@5.3.4, fast-xml-parser@5.3.6:
+  version "5.3.6"
+  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-5.3.6.tgz#85a69117ca156b1b3c52e426495b6de266cb6a4b"
+  integrity sha512-QNI3sAvSvaOiaMl8FYU4trnEzCwiRr8XMWgAHzlrWpTSj+QaCSvOf1h82OEP1s4hiAXhnbXSyFWCf4ldZzZRVA==
   dependencies:
-    strnum "^2.1.0"
+    strnum "^2.1.2"
 
 fb-watchman@^2.0.0:
   version "2.0.2"
@@ -5116,7 +5116,7 @@ strip-json-comments@^3.1.1:
   resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006"
   integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==
 
-strnum@^2.1.0:
+strnum@^2.1.2:
   version "2.1.2"
   resolved "https://registry.yarnpkg.com/strnum/-/strnum-2.1.2.tgz#a5e00ba66ab25f9cafa3726b567ce7a49170937a"
   integrity sha512-l63NF9y/cLROq/yqKXSLtcMeeyOfnSQlfMSlzFt/K73oIaD8DGaQWd7Z34X9GPiKqP5rbSh84Hl4bOlLcjiSrQ==

backend/compact-connect/tests/app/base.py

@@ -552,6 +552,15 @@ def _inspect_api_stack(self, api_stack: ApiStack):
                 },
             )
 
+        # When a custom domain is configured, verify the API Gateway domain uses TLS 1.2
+        if api_stack.hosted_zone is not None:
+            api_template.has_resource_properties(
+                'AWS::ApiGateway::DomainName',
+                {
+                    'SecurityPolicy': 'TLS_1_2',
+                },
+            )
+
     def _check_no_stack_annotations(self, stack: Stack):
         with self.subTest(f'Security Rules: {stack.stack_name}'):
             errors = Annotations.from_stack(stack).find_error('*', Match.string_like_regexp('.*'))

backend/compact-connect/tests/common_constructs/test_cognito_user_backup.py

@@ -31,12 +31,13 @@ class TestCognitoUserBackup(TestCase):
     def setUpClass(cls):
         """Set up test infrastructure."""
         cls.app = App()
-        # The persistent stack and layer are required for CognitoUserBackup, as an internal lambda depends on it
+        # The persistent stack and layer are required for CognitoUserBackup, as an internal lambda depends on it.
+        # Use a non-pipeline environment name so domain_name is not required (avoids HostedZone.from_lookup in tests).
         common_stack = AppStack(
             cls.app,
             'CommonStack',
             environment_context={},
-            environment_name='test',
+            environment_name='sandbox',
             standard_tags=StandardTags(project='compact-connect', service='compact-connect', environment='test'),
         )
         # Create common lambda layers

backend/compact-connect/tests/common_constructs/test_data_migration.py

@@ -17,12 +17,13 @@ def test_data_migration_synthesizes(self):
         from common_constructs.python_common_layer_versions import PythonCommonLayerVersions
 
         app = App()
-        # The persistent stack and layer are required for DataMigration, as an internal lambda depends on it
+        # The persistent stack and layer are required for DataMigration, as an internal lambda depends on it.
+        # Use a non-pipeline environment name so domain_name is not required (avoids HostedZone.from_lookup in tests).
         common_stack = AppStack(
             app,
             'CommonStack',
             environment_context={},
-            environment_name='test',
+            environment_name='sandbox',
             standard_tags=StandardTags(project='compact-connect', service='compact-connect', environment='test'),
         )
         # Create common lambda layers

backend/cosmetology-app/README.md

@@ -44,6 +44,23 @@ The `cdk.json` file tells the CDK Toolkit how to execute your app, including con
 deployment. You can add local configuration that will be merged into the `cdk.json['context']` values with a
 `cdk.context.json` file that you will not check in.
 
+### `ui_domain_name_override`
+
+**Important:** Because the cosmetology backend is hosted on a different domain than the shared frontend UI application (e.g. the
+backend hosted zone is `cosmetology.compactconnect.org` but the UI lives at `app.compactconnect.org`), each
+environment's context must include a `ui_domain_name_override` field that specifies the correct UI domain name. Without
+this override, the UI domain would be incorrectly derived from the backend's hosted zone (e.g.
+`app.cosmetology.compactconnect.org` instead of `app.compactconnect.org`). This value is used for CORS allowed origins,
+Cognito callback/logout URLs, and email template links.
+
+Example:
+```json
+{
+  "domain_name": "cosmetology.compactconnect.org",
+  "ui_domain_name_override": "app.compactconnect.org"
+}
+```
+
 This project is set up like a standard Python project. To use it, create and activate a python virtual environment
 using the tools of your choice (`pyenv` and `venv` are common).
 

backend/cosmetology-app/app_clients/README.md

@@ -56,9 +56,7 @@ The following scopes are available at the jurisdiction level:
 ```
 
 Currently, the most common scope needed by app clients is `{jurisdiction}/{compact}.write`, which allows uploading
-license data for a jurisdiction/compact combination. Scopes that expose PII (e.g., `.readSSN`, `.readPrivate`) should
-be granted sparingly and will require valid request signatures once a signing public key is configured for the
-jurisdiction.
+license data for a jurisdiction/compact combination.
 
 ### 3. Create App Client Using Interactive Python Script
 
@@ -108,143 +106,6 @@ link that you'll generate separately.
 As part of the email message sent to the consuming team, be sure to include the onboarding instructions document from
 the `it_staff_onboarding_instructions/` directory.
 
-## Managing API Signing Public Keys
-
-### Overview
-
-Signature-based authentication provides an additional layer of security for API access to sensitive licensure data. Each
-compact/state combination can have multiple SIGNATURE public keys configured to support key rotation and zero-downtime
-deployments.
-
-### Authorization Requirements
-
-**⚠️ CRITICAL SECURITY NOTICE:** Due to the sensitivity of the data protected by SIGNATURE authentication (including
-partial Social Security Numbers, personal addresses, and professional license details), configuration of new SIGNATURE
-public keys in production environments **MUST** include explicit authorization from the state board executive director.
-
-
-### Creating SIGNATURE Public Keys
-
-Once a state configures a public key, they will be able to access the SIGNATURE-required API endpoints. API endpoints with
-_optional_ SIGNATURE support will also begin to enforce SIGNATURE signatures for that combination of compact and state. **This
-means that, once a compact/state has a public key configured, they will be denied access to SIGNATURE-Optional endpoints,
-such as the `POST license` endpoint, unless they have also implemented SIGNATURE signatures there as well.** Be sure that
-the representative is advised that they should begin signing those requests _before_ CompactConnect has a configured
-public key.
-
-#### 1. Prerequisites
-
-Before creating a new SIGNATURE public key, ensure you have:
-- **Production Authorization**: Explicit approval from the state board executive director for production environments
-- Validated the identity of the individual providing the public key to you
-- Jurisdiction and compact information confirmed
-- Contact information for the state IT representative
-- The public key file (`.pub` format) from the state IT representative (copy it to the same directory you are running the script from). The name of the file must match the key id.
-- AWS credentials configured with permissions to write to the compact configuration table
-- Python 3.10+ installed with boto3 dependency (`pip install boto3`)
-
-#### 2. Key ID Naming Convention
-
-The state IT department should provide an identifier; however, you can recommend a descriptive key ID that includes:
-- Environment indicator (if applicable)
-- Version or date suffix
-
-Examples:
-- `prod-key-001`
-- `beta-key-2024-01`
-
-#### 3. Create SIGNATURE Public Key Using Interactive Python Script
-
-**Use the provided Python script in the bin directory for streamlined SIGNATURE key management:**
-
-```bash
-python3 bin/manage_signature_keys.py create -t <compact_configuration_table_name>
-```
-
-**Interactive Process:**
-The script will prompt you for:
-- Compact (cosm)
-- State postal abbreviation (e.g., "ky", "la")
-- Key ID (e.g., "client-org-prod-key-001")
-
-**File Reading:**
-The script will:
-- Notify you that it will read the public key from `<key-id>.pub`
-- Validate the PEM format of the public key
-- Check for existing keys with the same ID
-- Write the key to the compact configuration database
-
-**⚠️NOTICE:** Once the public key has been successfully stored, remove the `.pub` file from the directory to ensure it
-is never accidentally checked into the project.
-
-#### 4. Database Schema
-
-SIGNATURE keys are stored in the compact configuration table with the following schema:
-- **Primary Key (pk)**: `{compact}#SIGNATURE_KEYS#{state}`
-- **Sort Key (sk)**: `{compact}#JURISDICTION#{jurisdiction}#{key_id}`
-- **Additional Fields**:
-  - `publicKey`: PEM-encoded public key content
-  - `compact`: Compact abbreviation
-  - `jurisdiction`: Jurisdiction abbreviation
-  - `keyId`: Key identifier
-  - `createdAt`: Creation timestamp
-
-### Deleting SIGNATURE Public Keys
-
-#### 1. Prerequisites
-
-Before deleting a SIGNATURE public key, ensure you have:
-- Confirmation that the key is no longer in use by the state IT department
-- Confirmation of the key id to be deleted
-- Understanding of the impact on API access for the compact/state combination
-
-#### 2. Delete SIGNATURE Public Key Using Interactive Python Script
-
-```bash
-python3 bin/manage_signature_keys.py delete -t <table_name>
-```
-
-**Interactive Process:**
-The script will:
-- Prompt for compact and state
-- List all existing keys for the compact/state combination
-- Allow you to select the specific key ID to delete
-- Require typing "DELETE" to confirm the deletion
-- Remove the key from the compact configuration database
-
-### Key Rotation Best Practices
-
-#### 1. Planning
-
-- Coordinate with the State IT representative well in advance
-- Plan for zero-downtime deployment
-
-#### 2. Implementation
-
-- Create new keys before removing old ones
-- Allow both keys to be active during the transition period
-- Monitor API access and authentication success rates
-- Remove old keys only after confirming new keys are working correctly
-
-#### 3. Documentation
-
-- Document key rotation dates and reasons
-- Maintain audit trail of all key management activities
-
-### Security Considerations
-
-#### 1. Key Storage
-
-- Public keys are stored in DynamoDB with appropriate access controls
-- Private keys should never be stored in CompactConnect systems
-- State IT departments are responsible for secure private key management
-
-#### 2. Access Control
-
-- Only authorized technical staff should have access to key management resources
-- All key management activities should be logged and audited
-- Production key creation requires executive director approval
-
 ## Rotating App Client Credentials
 
 Unfortunately, AWS Cognito does not support rotating app client credentials for an existing app client. The only way

backend/cosmetology-app/bin/generate_mock_license_csv_upload_file.py

@@ -44,7 +44,6 @@
 
 FIELDS = (
     'ssn',
-    'npi',
     'licenseNumber',
     'licenseType',
     'licenseStatus',
@@ -146,10 +145,8 @@ def get_mock_license(
     license_data = {
         #                                              |Zero padded 4 digit int|
         'ssn': f'{ssn_prefix}-{(i // 10_000) % 100:02}-{(i % 10_000):04}',
-        # Some have NPI, some don't
-        'npi': str(randint(1_000_000_000, 9_999_999_999)) if choice([True, False]) else None,
-        # Some have License number, some don't
-        'licenseNumber': generate_mock_license_number() if choice([True, False]) else None,
+        # licenseNumber is required
+        'licenseNumber': generate_mock_license_number(),
         'licenseType': choice(LICENSE_TYPES[compact]),
         'givenName': name_faker.first_name(),
         'middleName': name_faker.first_name(),