[CORE-8147] deprecated filestack

Author: trtshen

docs/upgrades/angular-18-to-19-security-fixes.md

@@ -341,6 +341,37 @@ review and update as needed:
 - `Apollo.use()`, `Apollo.watchQuery()`, `Apollo.mutate()`, `Apollo.query()` signatures
 - check for changes in `ApolloModule.forRoot()` vs standalone provider pattern
 
+### 5.5. Lambda@Edge forwarder — S3 path prefix (COMPLETED March 2026)
+
+**Root cause:** The Angular 19 `application` builder (`@angular-devkit/build-angular ^19`) changed the build output structure by introducing a `browser/` subdirectory:
+
+| Builder | Angular version | Output path | S3 key prefix |
+|---------|-----------------|-------------|---------------|
+| `browser` (webpack) | 17 / 18 | `dist/v3/{locale}/` | `/{locale}/` |
+| `application` (esbuild) | **19+** | `dist/v3/browser/{locale}/` | `/browser/{locale}/` |
+
+This mismatch caused `lambda/forwarder/index.js` to rewrite all CloudFront URIs to non-existent S3 keys (e.g. `/en-US/index.html` instead of `/browser/en-US/index.html`). S3 returned `403 AccessDenied` — surfaced as raw XML to every user loading the app.
+
+**Fix applied to `lambda/forwarder/index.js`:**
+
+```javascript
+// before (Angular 17/18)
+request.uri = "/en-US/index.html";          // fallback
+request.uri = `/${locale}/index.html`;      // spa route
+// (no static-asset rewrite needed — assets were at root)
+
+// after (Angular 19+)
+request.uri = "/browser/en-US/index.html";         // fallback
+request.uri = `/browser/${locale}/index.html`;    // spa route
+} else if (!request.uri.startsWith('/browser/')) {
+    request.uri = `/browser${request.uri}`;         // static assets
+}
+```
+
+**Validation:** Confirmed working on `p2-stage` after deployment (March 2026).
+
+**Future Angular upgrades:** check `ls dist/v3/` after building to verify the output structure before merging. If thenstructure changes again, update `forwarder/index.js` in the same PR. See `lambda/README.md` for the full dependency documentation.
+
 ---
 
 ## Phase 6 — Testing & Validation
@@ -446,6 +477,7 @@ npm audit > ./output/angular-19-upgrade-audit.log 2>&1
 | TypeScript 5.6 stricter checks | incremental fix of any new type errors |
 | ngx-quill v27 regressions | minimal risk — usually just peer dep bump |
 | CI build failures | run full CI pipeline before merging |
+| **Lambda@Edge S3 path mismatch** (**occurred** March 2026) | Angular 19 `application` builder adds `browser/` subdirectory; `lambda/forwarder/index.js` must be updated in the same PR — see §5.5 |
 
 **Rollback plan:** revert to the pre-upgrade commit on `angular-eos-upgrades-prerelease` branch. all changes are confined to `package.json`, `package-lock.json`, and targeted source fixes.
 
@@ -480,10 +512,13 @@ npm audit > ./output/angular-19-upgrade-audit.log 2>&1
   - [ ] update uppy service/component if API changed
   - [ ] update apollo-angular usage if API changed
   - [ ] fix any Angular 19 deprecation warnings
+  - [x] update `lambda/forwarder/index.js` for `browser/` path prefix *(completed March 2026)*
 - [ ] **Phase 6:** Validation
   - [ ] `npm run prebuildv3` succeeds
   - [ ] `ng build v3` succeeds
   - [ ] `npm test` passes
   - [ ] `npm run lint` passes
   - [ ] `npm audit` shows reduced vulnerability count
   - [ ] manual testing on staging
+    - [ ] verify app loads at `https://app.<stack>.practera.com/en-US` without S3 AccessDenied
+    - [ ] verify deep-links with query params (magic-link login) resolve to correct locale

lambda/README.md

@@ -1,10 +1,76 @@
 ### Description
 
-This directory will hold `lambda@edge` functions.
+This directory holds `lambda@edge` functions deployed to CloudFront as `origin-request` handlers.
 
-`forwarder` - lambda function that sits infront of the CDN, handles `globalization` redirection.
-`versioner` - function to create lambda function version.
+`forwarder` - rewrites incoming CloudFront URIs to the correct S3 object keys for the Angular i18n locale builds.
+`versioner` - creates a numbered Lambda version ARN that CloudFront requires for Lambda@Edge associations.
+
+---
+
+### i18n / Angular Build Output Dependency
+
+The `forwarder` function is **tightly coupled** to the Angular build output directory structure. Breaking this coupling causes S3 `AccessDenied` (403) errors surfaced as raw XML to end users.
+
+#### How Angular i18n builds are deployed
+
+`projects/v3` is compiled with `"localize": true` in `angular.json`, producing one subfolder per locale:
+
+| Angular version | Build output path | S3 object key prefix |
+|-----------------|-------------------|----------------------|
+| 17 / 18 (webpack builder) | `dist/v3/{locale}/` | `/{locale}/` |
+| **19+ (application builder)** | `dist/v3/browser/{locale}/` | `/browser/{locale}/` |
+
+The `aws s3 sync dist/v3/ s3://$BUCKET --delete` step (CI/CD step 22) mirrors this structure directly into S3, so the S3 key prefix always matches the build output.
+
+#### What the forwarder does
+
+CloudFront does **not** forward query strings to S3 (`QueryString: false`). When a user visits a deep-link such as `/en-US?auth_token=…`, CloudFront calls the forwarder with `request.uri = "/en-US"`. The forwarder:
+
+1. Extracts the first path segment as the locale (`en-US`, `ja`, `ms`, `es`).
+2. For unknown locales or bare `/`, falls back to the default locale.
+3. For SPA routes (no file extension), rewrites to `/{prefix}/{locale}/index.html`.
+4. For static assets (with file extension), rewrites to `/{prefix}{original_uri}`.
+5. Passes `version.json` requests through unchanged (whitelist).
+
+#### Supported locales
+
+The locale whitelist in `forwarder/index.js` must stay in sync with the locales configured in `angular.json`:
+
+```javascript
+const locales = ["en-US", "ja", "ms", "es"];
+```
+
+To add a new locale: update both `angular.json` (`i18n.locales`) **and** the `locales` array in `forwarder/index.js`.
+
+#### ⚠️ What to check on every Angular major version upgrade
+
+When upgrading Angular major versions, verify the build output structure has not changed before deploying:
+
+```bash
+# after building, check what subdirectories are produced
+ls dist/v3/
+# Angular 19+: should show  browser/
+# Angular 17/18: should show  en-US/  ja/  ms/  es/
+```
+
+If the output structure changes, update the path prefix in `forwarder/index.js` **before** merging to trunk so both changes deploy together in the same CI/CD run.
+
+#### Incident history
+
+| Date | Trigger | Symptom | Fix |
+|------|---------|---------|-----|
+| March 2026 | Angular 18 → 19 upgrade | S3 `AccessDenied` XML shown to all users on `app.p2-stage.practera.com` | Added `/browser/` prefix to all rewritten URIs in `forwarder/index.js` |
+
+---
 
 ### Deployment
 
-Once `AWS` credentials is ready, just run `deploy.sh`. Make sure you installed [sam](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) on your machine.
+Once `AWS` credentials are ready, run `deploy.sh`. Requires [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html).
+
+In CI/CD (`p2-stage-appv3.yml`) the deploy sequence is:
+1. Build Angular app (`ng build v3`)
+2. Deploy Lambda@Edge (`bash lambda/deploy.sh`) → exports `HandlerVersionArn`
+3. Deploy CloudFormation/Serverless stack (picks up new `HandlerVersionArn`)
+4. Sync `dist/v3/` to S3
+
+Both the Lambda function and the S3 content must reflect the same output path structure.

lambda/forwarder/index.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-exports.handler = async (evt, context, cb) => {
+exports.handler = async (evt) => {
   const { request } = evt.Records[0].cf;
 
   console.log(`Original Uri: ${request.uri}`);
@@ -11,21 +11,27 @@ exports.handler = async (evt, context, cb) => {
   const locales = ["en-US", "ja", "ms", "es"];
   const lastPartUrl = uriParts[uriParts.length - 1];
 
-  // whitelisted version.json request
+  // whitelisted version.json request — note: query strings are in request.querystring,
+  // not in request.uri, so only the path filename is tested here
   console.log("trailingURL::", lastPartUrl);
-  if (lastPartUrl.match(/^version\.json(?:\?t=\d+)?$/) !== null) {
-    return cb(null, request);
+  if (lastPartUrl.match(/^version\.json$/) !== null) {
+    return request;
   }
 
   if (locale === "" || locale === "index.html" || !locales.includes(locale)) {
     request.uri = "/en-US/index.html";
     console.log("Go to default page and locale.");
-    return cb(null, request);
+    return request;
   }
 
   const fileExt = path.extname(lastPartUrl);
-  if (!fileExt) request.uri = `/${locale}/index.html`;
+  if (!fileExt) {
+    request.uri = `/browser/${locale}/index.html`;
+  } else if (!request.uri.startsWith('/browser/')) {
+    // rewrite static asset paths to match Angular 19+ application builder output
+    request.uri = `/browser${request.uri}`;
+  }
 
   console.log(`New Uri: ${request.uri}`);
-  return cb(null, request);
+  return request;
 };

lambda/forwarder/template.yml

@@ -37,7 +37,7 @@ Resources:
     Properties:
       Handler: index.handler
       CodeUri: ./bin/handler.zip
-      Runtime: nodejs18.x
+      Runtime: nodejs22.x
       Timeout: 10
       Role: !GetAtt HandlerRole.Arn
   HandlerVersion:
@@ -53,4 +53,4 @@ Outputs:
     Description: "Arn Version for Lambda function to associate unto CDN"
     Value: !GetAtt HandlerVersion.FunctionArn
     Export:
-      Name: !Sub "${StackName}-HandlerVersion-${Env}"
+      Name: !Sub "${StackName}-HandlerVersion-${Env}"

lambda/versioner/template.yml

@@ -19,7 +19,7 @@ Resources:
     Properties:
       Handler: index.handler
       CodeUri: ./bin/handler.zip
-      Runtime: nodejs18.x
+      Runtime: nodejs22.x
       Timeout: 10
       Role: !GetAtt LambdaVersionHelperRole.Arn
   LambdaVersionHelperRole:
@@ -51,4 +51,4 @@ Outputs:
     Description: "Lambda Function Versioner ARN"
     Value: !GetAtt Versioner.Arn
     Export:
-      Name: !Sub "${StackName}-LambdaVersionerArn-${Env}"
+      Name: !Sub "${StackName}-LambdaVersionerArn-${Env}"

package.json

@@ -61,7 +61,6 @@
     "core-js": "^3.21.1",
     "dayjs": "^1.11.10",
     "exif-js": "^2.3.0",
-    "filestack-js": "^3.30.0",
     "franc-min": "^6.2.0",
     "graphql": "^16.8.1",
     "ics": "^3.7.2",

projects/v3/src/app/components/activity/activity.component.scss

@@ -45,6 +45,6 @@
 }
 
 .focusable:focus {
-  border: 1px solid var(--ion-color-primary);
-  display: flex;
+  outline: 2px solid var(--ion-color-primary);
+  outline-offset: -2px;
 }

projects/v3/src/app/components/components.module.ts

@@ -18,8 +18,7 @@ import { FastFeedbackComponent } from './fast-feedback/fast-feedback.component';
 import { ReviewRatingComponent } from './review-rating/review-rating.component';
 import { CircleProgressComponent } from './circle-progress/circle-progress.component';
 import { NgCircleProgressModule } from 'ng-circle-progress';
-import { FilestackComponent } from './filestack/filestack.component';
-import { FilestackPreviewComponent } from './filestack-preview/filestack-preview.component';
+import { FilePreviewComponent } from './file-preview/file-preview.component';
 import { ContactNumberFormComponent } from './contact-number-form/contact-number-form.component';
 import { ClickableItemComponent } from './clickable-item/clickable-item.component';
 import { AssessmentComponent } from './assessment/assessment.component';
@@ -90,8 +89,7 @@ const largeCircleDefaultConfig = {
     FilePopupComponent,
     FileDisplayComponent,
     VideoConversionComponent,
-    FilestackComponent,
-    FilestackPreviewComponent,
+    FilePreviewComponent,
     ImgComponent,
     ListItemComponent,
     LockTeamAssessmentPopUpComponent,
@@ -136,8 +134,7 @@ const largeCircleDefaultConfig = {
     FilePopupComponent,
     FileDisplayComponent,
     VideoConversionComponent,
-    FilestackComponent,
-    FilestackPreviewComponent,
+    FilePreviewComponent,
     ImgComponent,
     IonicModule,
     ListItemComponent,

projects/v3/src/app/components/file-display/file-display.component.spec.ts

@@ -2,7 +2,6 @@
 import { CUSTOM_ELEMENTS_SCHEMA, SimpleChange, DebugElement } from '@angular/core';
 import { ComponentFixture, TestBed, fakeAsync, flushMicrotasks, waitForAsync, tick } from '@angular/core/testing';
 import { FileDisplayComponent } from './file-display.component';
-import { FilestackService } from '@v3/services/filestack.service';
 import { ReactiveFormsModule, FormControl } from '@angular/forms';
 import { UtilsService } from '@v3/services/utils.service';
 import { TestUtils } from '@testingv3/utils';
@@ -19,7 +18,6 @@ class OnChangedValues extends SimpleChange {
 describe('FileDisplayComponent', () => {
   let component: FileDisplayComponent;
   let fixture: ComponentFixture<FileDisplayComponent>;
-  let filestackSpy: jasmine.SpyObj<FilestackService>;
   let utilsSpy: jasmine.SpyObj<UtilsService>;
 
   beforeEach(waitForAsync(() => {
@@ -32,14 +30,6 @@ describe('FileDisplayComponent', () => {
           provide: UtilsService,
           useClass: TestUtils,
         },
-        {
-          provide: FilestackService,
-          useValue: jasmine.createSpyObj('FilestackService', [
-            'previewFile',
-            'getWorkflowStatus',
-            'metadata'
-          ])
-        },
         {
           provide: ModalController,
           useValue: jasmine.createSpyObj('ModalController', {
@@ -55,7 +45,6 @@ describe('FileDisplayComponent', () => {
   beforeEach(() => {
     fixture = TestBed.createComponent(FileDisplayComponent);
     component = fixture.debugElement.componentInstance;
-    filestackSpy = TestBed.inject(FilestackService) as jasmine.SpyObj<FilestackService>;
     utilsSpy = TestBed.inject(UtilsService) as jasmine.SpyObj<UtilsService>;
   });
 

projects/v3/src/app/components/file-display/file-display.component.ts

@@ -11,8 +11,8 @@ import { FileInput, TusFileResponse } from '../types/assessment';
 import { FilePopupComponent } from '../file-popup/file-popup.component';
 import { ModalController } from '@ionic/angular';
 
-// @TODO: make compatible with FileStack format (remove when no longer needed)
-interface FileStackCompatible extends TusFileResponse {
+// backward-compatible file type that includes legacy property names
+interface DisplayableFile extends TusFileResponse {
   filename: string;
   mimetype: string;
   url: string;
@@ -26,7 +26,7 @@ interface FileStackCompatible extends TusFileResponse {
 })
 export class FileDisplayComponent {
   @Input() fileType: string = 'any';
-  @Input() file?: FileStackCompatible;
+  @Input() file?: DisplayableFile;
   @Input() isFileComponent: boolean = false; // flag parent component is FileComponent
   @ViewChild('videoEle') videoEle?: ElementRef = new ElementRef(null);
   @Output() removeFile: EventEmitter<any> = new EventEmitter<any>();