Merge branch 'susdocs' of https://github.com/Software-Hardware-Integration-Lab/Documentation into susdocs

Author: JelaniB-sec

.vscode/launch.json

@@ -10,8 +10,7 @@ Below is a list of all environmental variable configurations that the server can
 
 The title of the section is the name of the environmental variable.
 
-For authentication configuration, please see here for more environmental variables that are supported by SHI URL Shortener via the Microsoft Authentication Library for Node.JS (@azure/identity):
-<https://www.npmjs.com/package/@azure/identity#environment-variables>
+For authentication configuration, please see here for more environmental variables that are supported by SUS via the Microsoft Authentication Library for Node.JS [@azure/identity](https://www.npmjs.com/package/@azure/identity#environment-variables){:target="_blank"}.
 
 ---
 
@@ -20,67 +19,77 @@ For authentication configuration, please see here for more environmental variabl
 - Mandatory: `true`
 - Expected string format: GUID
 - Allowed values: GUID
+- Default Value: `00000000-0000-0000-0000-000000000000`
 - Description: Tenant ID of the tenant that the app considers home/authenticates to. Defaults to NULL if not defined and should be overridden during authentication engine start.
 
 ## `SUS_DB_Host`
 
 - Mandatory: `false`
 - Expected string format: string
 - Allowed values: string
+- Default Value: `localhost`
 - Description: Host name of the Azure SQL DB that should be used for storing simple data.
 
 ## `SUS_DB_Name`
 
 - Mandatory: `false`
 - Expected string format: string
 - Allowed values: string
+- Default Value: `UrlShortener`
 - Description: Name of the DB to access and use for relational data storage. This is necessary for Azure SQL DBs as the DB has to be created ahead of time and shouldn't be created inline as a best practice.
 
 ## `SUS_Debug`
 
 - Mandatory: `false`
 - Expected string format: boolean
 - Allowed values: true
+- Default Value: `false`
 - Description: Flag that indicates if the API service should be in debug mode.
 
 ## `SUS_Headless`
 
 - Mandatory: `false`
 - Expected string format: boolean
 - Allowed values: true
+- Default Value: `false`
 - Description: Flag that indicates the system should run with no user interface render.
 
 ## `SUS_LocalDb`
 
 - Mandatory: `false`
 - Expected string format: boolean
 - Allowed values: true
+- Default Value: `false`
 - Description: Flag that indicates the SQLite should be used for the ORM. All other functions are untouched.
 
 ## `SUS_Local`
 
 - Mandatory: `false`
 - Expected string format: boolean
 - Allowed values: true
-- Description: Flag that controls if the server should run with local resources only. This uses SQLite and Azurite as the storage engines and endpoints.
+- Default Value: `false`
+- Description: Flag that controls if the server should run with local resources only. This uses SQLite and prevents external resource calls allowing for a true local only execution experience.
 
 ## `SUS_DefaultTarget`
 
 - Mandatory: `false`
 - Expected string format: URL
 - Allowed values: URL
+- Default Value: `https://shi.com`
 - Description: Location that the service will redirect to if a match is not found.
 
 ## `SUS_AuthAudience`
 
-- Mandatory: `false`
+- Mandatory: `true`
 - Expected string format: GUID
 - Allowed values: GUID
-- Description: Ensure that a client ID is provided if not in debug mode for authentication
+- Default Value: `00000000-0000-0000-0000-000000000000`
+- Description: Application ID of the app registration to use as the audience value in the access token validation. Not mandatory if in debug mode as auth is not enforced in debug mode.
 
 ## `SUS_Test`
 
 - Mandatory: `false`
 - Expected string format: boolean
 - Allowed values: true
+- Default Value: `false`
 - Description: Flag that indicates if the application should have special behavior based on if the system is running through automated QA.

docs/URL-Shortener/Reference/Development/Workflow.md

@@ -2,22 +2,21 @@
 
 ## Overview
 
-The **SHI - URL Shortener (SUS)** is a security-focused privacy, respecting, compliance-ready URL redirection service. SUS provides controlled creation and management of short URLs, delegated administration through RBAC, strong input validation, and guardrails to prevent misuse (e.g., banned terms, domain scoping).
+The **SHI - URL Shortener (SUS)** is a security-focused, privacy respecting, compliance-ready URL redirection service. SUS provides controlled creation and management of short URLs, delegated administration through RBAC, strong input validation, and guardrails to prevent misuse (e.g., banned terms, domain scoping).
 
 ## Audience
 
-This documentation is primarily intended for technical users who are responsible for deploying, configuring, and maintaining the URL Shortener and Redirector service within customer environments. While the content is geared toward technical implementation, it is written to be accessible to non-technical stakeholders as well.
+This documentation is primarily intended for technical users who are responsible for deploying, configuring, and maintaining the URL Shortener service within customer environments. While the content is geared toward technical implementation, it is written to be accessible to non-technical stakeholders as well.
 
 ## SUS in the Security Landscape
 
 - Zero trust: Every request re‑validated (types, UUID formats, filter shapes).
 - Strong runtime validation: Uses structural equality/type guards to reject malformed inputs early (400).
 - Principle of least privilege: Distinct scopes required for privileged sets (e.g., domain & ban list modifications).
-- Protective lists: Banned terms and controlled domains mitigate phishing / brand abuse.
-- Deterministic errors: Explicit 400 (input), 404 (not found), 204 (successful deletes).
+- Protective lists: Banned terms and controlled domains for fine grained control over what is created by end users.
 - Separation of concerns: Routing layer delegates business logic to a Redirect Engine singleton.
-- Minimal disclosure: Nonexistent records yield 404 without leaking broader state.
-- Auditable mutation points: Create/Update/Delete paths are centralized for logging (implementation hook).
+- Minimal disclosure: Nonexistent management records yield 404 without leaking broader state.
+- Auditable mutation points: Create/Update/Delete paths are centralized for logging.
 
 ## Prerequisites
 

docs/URL-Shortener/Reference/Settings/Environment-Variables-Reference.md

@@ -1,3 +1,16 @@
+.susIcon {
+    /* Detaches the icon from being dependant on other HTML elements for its render. */
+    display: inline-block;
+    /* Size of the icon to be rendered. */
+    font-size: 1.5em;
+    /* Prevent the line from getting larger as the icon does. */
+    line-height: 1;
+    /* Prevent the line from getting larger as the icon does. */
+    height: 1em;
+    /* Ensure that the icon renders in the center of the line, equal with the following text. */
+    vertical-align: middle;
+}
+
 /* Light mode */
 [data-md-color-scheme="default"] {
     --md-default-bg-color: white;
@@ -25,4 +38,4 @@
 [data-md-color-scheme="slate"] .md-tooltip--active {
     color: black;
     background-color: white;
-}
+}

docs/URL-Shortener/index.md

@@ -46,20 +46,20 @@ hide:
 </div>
 
 <div class="grid cards" align="center" markdown>
-- :globe_with_meridians:{ .lg .middle } __SHI - Data Gateway__
+- :material-database-outline:{ .lg .middle } __SHI - Data Gateway__
 
     ---
 
-    Store and retrieve data for the various SHI Lab products.
+    Stores and retrieves the data for various SHI Lab products.
 
     [:octicons-arrow-right-24: Overview](Data-Gateway/index.md)
 
 <div class="grid cards" align="center" markdown>
-- <span style="font-size: 2em;">ඞ</span> __SHI - URL Shortener__
+- <span class="susIcon">ඞ</span> __SHI - URL Shortener__
 
     ---
 
-    Issue short, governed redirect links that map friendly paths (sources) to vetted destination URLs.
+    Issue short, compliant, governed redirect links that map friendly paths to destination URLs.
 
     [:octicons-arrow-right-24: Overview](URL-Shortener/index.md)
 </div>

docs/assets/Styles/common.css

@@ -8,3 +8,4 @@
 *[BYOK]: Bring Your Own Key
 *[HYOK]: Hold Your Own Key
 *[CMK]: Customer-Managed Key
+*[SUS]: SHI - URL Shortener

docs/index.md

@@ -237,19 +237,17 @@ nav:
           - Overview: Data-Gateway/Reference/index.md
       - Troubleshooting: Data-Gateway/Troubleshooting.md
 
-
   - URL Shortener:
-        - Overview: URL-Shortener/index.md
-        - Prerequisites:
-            - Overview: URL-Shortener/Prerequisites/index.md
-            - Authorization & RBAC: URL-Shortener/Prerequisites/Authorization-&-RBAC.md
-            - Graph API Permissions: URL-Shortener/Prerequisites/Graph-API-Permissions.md
-            - Getting Started: URL-Shortener/Getting-Started.md
-        - Usage Guide: URL-Shortener/Usage-Guide.md
-        - Reference:
-            - Settings:
-                - Environment Variables: URL-Shortener/Reference/Settings/Environment-Variables-Reference.md
-            - Development:
-                - OpenAPI Spec: URL-Shortener/Reference/Development/OpenAPI.md
-                - Workflow: URL-Shortener/Reference/Development/Workflow.md
-                - Server Setup: URL-Shortener/Reference/Development/Server-Setup.md
+      - Overview: URL-Shortener/index.md
+      - Prerequisites:
+          - Overview: URL-Shortener/Prerequisites/index.md
+          - Authorization & RBAC: URL-Shortener/Prerequisites/Authorization-&-RBAC.md
+          - Graph API Permissions: URL-Shortener/Prerequisites/Graph-API-Permissions.md
+          - Getting Started: URL-Shortener/Getting-Started.md
+      - Usage Guide: URL-Shortener/Usage-Guide.md
+      - Reference:
+          - Settings:
+              - Environment Variables: URL-Shortener/Reference/Settings/Environment-Variables-Reference.md
+          - Development:
+              - OpenAPI Spec: URL-Shortener/Reference/Development/OpenAPI.md
+              - Server Setup: URL-Shortener/Reference/Development/Server-Setup.md

includes/abbreviations.md

@@ -2,14 +2,16 @@
 
 {% block extrahead %}
 
-<meta name="keywords" content="SHI,Microsoft,M365,License,Document,Security,Intune,Defender,Entra,Automation,SHIELD">
+<meta name="keywords"
+  content="SHI,Microsoft,M365,License,Document,Security,Intune,Defender,Entra,Automation,SHIELD,SUS,Data Gateway">
 <meta name="robots" content="index, follow">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <meta name="language" content="English">
 <meta name="revisit-after" content="8 days">
 <meta name="author" content="SHI International Corp.">
-<meta property='og:title' content='SHI Orchestration Platform - Documentation' />
-<meta property='og:description' content='Documentation for the SHI Orchestration Platform (SOP). Part of SHI Lab.' />
+<meta property='og:title' content='SHI Lab - Product Documentation' />
+<meta property='og:description'
+  content='Documentation for the SHI Lab suite of products, including: SHIELD, Data Gateway, SUS, and more...' />
 <meta property='og:image' content='https://docs.shilab.com/assets/Images/Favicon.png' />
 <meta property='og:url' content='https://shi.com/' />
 <meta property='og:image:width' content='980' />
@@ -19,19 +21,19 @@
 
 <!-- Microsoft Clarity -->
 <script type="text/javascript">
-  ( function ( c, l, a, r, i, t, y ) {
-    c[ a ] = c[ a ] || function () { ( c[ a ].q = c[ a ].q || [] ).push( arguments ); };
-    t = l.createElement( r ); t.async = 1; t.src = "https://www.clarity.ms/tag/" + i;
-    y = l.getElementsByTagName( r )[ 0 ]; y.parentNode.insertBefore( t, y );
-  } )( window, document, "clarity", "script", "mjm7g9aobr" );
+  (function (c, l, a, r, i, t, y) {
+    c[a] = c[a] || function () { (c[a].q = c[a].q || []).push(arguments); };
+    t = l.createElement(r); t.async = 1; t.src = "https://www.clarity.ms/tag/" + i;
+    y = l.getElementsByTagName(r)[0]; y.parentNode.insertBefore(t, y);
+  })(window, document, "clarity", "script", "mjm7g9aobr");
 
   /** Contains the state of all consent as defined by the Material Theme. Used to see if consent has been granted for cookies. */
-  var consent = __md_get( "__consent" );
+  var consent = __md_get("__consent");
 
   // Check if consent was granted for Microsoft Clarity
-  if ( consent && consent.clarity ) {
+  if (consent && consent.clarity) {
     /* The user accepted the cookie */
-    window.clarity( 'consent' );
+    window.clarity('consent');
   } else {
     /* The user rejected the cookie */
     // Do nothing
@@ -40,4 +42,4 @@
 
 
 {{ super() }}
-{% endblock %}
+{% endblock %}

mkdocs.yml

@@ -1,4 +1,4 @@
 mkdocs == 1.6.1
-mkdocs-material == 9.6.19
+mkdocs-material == 9.6.22
 mkdocs-glightbox == 0.5.1