Updated to beginnings of real dev env, including github pipeline

Author: richardtape

.env.example

@@ -0,0 +1,53 @@
+# -----------------------------------------------------------------------------
+# BIOCBOT Environment Configuration
+#
+# Copy this file to .env and fill in the appropriate values for your
+# development environment.
+# -----------------------------------------------------------------------------
+
+# --- Core Application Settings ---
+# The port the Node.js server will run on.
+# IMPORTANT: This MUST match the port used in the SAML_CALLBACK_URL and the
+# `saml20-sp-remote.php` configuration in the docker-simple-saml project.
+PORT=8050
+
+# --- TLEF Server Integration (Optional) ---
+# If you are connecting this bot to a TLEF-SERVER instance, provide its URL.
+TLEF_SERVER_URL=http://localhost:8000
+BIOCBOT_API_KEY=your-tlef-server-api-key
+
+# --- Session Management ---
+# A long, random string used to sign the session ID cookie.
+SESSION_SECRET=a-very-secret-string-for-sessions
+
+# Session timeout in milliseconds (Default: 7200000 = 2 hours)
+SESSION_TIMEOUT_MS=7200000
+
+# --- SAML (Single Sign-On / Single Log-Out) Configuration ---
+# These values MUST correspond to the configuration of your SAML Identity Provider (IdP).
+# For local development, this is likely the `docker-simple-saml` project.
+
+# The entry point for SAML login requests at your IdP.
+SAML_ENTRY_POINT=http://localhost:8080/simplesaml/saml2/idp/SSOService.php
+
+# The URL for SAML Single Log-Out (SLO) requests at your IdP.
+SAML_LOGOUT_URL=http://localhost:8080/simplesaml/saml2/idp/SingleLogoutService.php
+
+# The unique identifier for this application (the "Service Provider" or "SP").
+# IMPORTANT: This MUST exactly match the `entityid` configured for this SP
+# in your IdP's `saml20-sp-remote.php` file.
+SAML_ISSUER=https://tlef-biocbot
+
+# The full URL where the IdP will send the SAML response after a user logs in.
+# The port number here MUST match the PORT variable above.
+SAML_CALLBACK_URL=http://localhost:8050/auth/saml/callback
+
+# The full URL where the IdP will redirect the user after they have logged out.
+# The port number here MUST match the PORT variable above.
+SAML_LOGOUT_CALLBACK_URL=http://localhost:8050/auth/logout/callback
+
+# The path to the IdP's public certificate, used to verify SAML response signatures.
+# IMPORTANT: For `docker-simple-saml`, this `server.crt` file is generated when the
+# SAML container starts. You must copy it from the `docker-simple-saml` project
+# into the `./certs/` directory of this project.
+SAML_CERT_PATH=./certs/server.crt

.github/workflows/deploy.yml

@@ -0,0 +1,41 @@
+# .github/workflows/deploy.yml
+
+name: Deploy to Staging
+
+on:
+    push:
+        branches:
+            - main
+
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Setup SSH
+              uses: webfactory/[email protected]
+              with:
+                  ssh-private-key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
+
+            - name: Deploy to server
+              run: |
+                  # Add the server's host key using the secret
+                  ssh-keyscan -H ${{ secrets.STAGING_SERVER_IP }} >> ~/.ssh/known_hosts
+
+                  # SSH into the server using the secret
+                  ssh deployer@${{ secrets.STAGING_SERVER_IP }} << 'EOF'
+                    # Navigate to the application directory
+                    cd /var/www/biocbot-staging
+
+                    # Pull the latest code from the main branch
+                    git pull origin main
+
+                    # Install/update npm dependencies
+                    npm install --production
+
+                    # Restart the application service
+                    sudo systemctl restart biocbot-staging
+                  EOF

.gitignore

@@ -1,136 +1,6 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-.pnpm-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
 node_modules/
-jspm_packages/
-
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Microbundle cache
-.rpt2_cache/
-.rts2_cache_cjs/
-.rts2_cache_es/
-.rts2_cache_umd/
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
 .env
-.env.development.local
-.env.test.local
-.env.production.local
-.env.local
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# yarn v2
-.yarn/cache
-.yarn/unplugged
-.yarn/build-state.yml
-.yarn/install-state.gz
-.pnp.*
+.DS_Store
+certs/
+*.crt
+*.pem

README.md

@@ -1 +1,79 @@
-# tlef-biocbot
+# BIOCBOT SAML Example Application
+
+This project serves as an example of a Node.js web application that uses SAML for user authentication. It demonstrates how to integrate with a SAML Identity Provider (IdP) for both login (SSO) and logout (SLO), and how to manage application state based on authentication status.
+
+See https://github.com/ubc/docker-simple-saml for the SAML provider you can run locally.
+
+The backend is built with Express.js and Passport.js, using the `passport-saml` strategy. The frontend is built with vanilla JavaScript using Web Components.
+
+## Project Structure
+
+The repository is organized into two main parts:
+
+-   `public/`: Contains all client-side code, including HTML, CSS, and JavaScript for the frontend application.
+-   `src/`: Contains all server-side Node.js code, including the Express server, API routes, and authentication middleware.
+
+---
+
+## Backend (`src/`)
+
+The backend is responsible for serving the frontend application, handling API requests, and managing the SAML authentication lifecycle.
+
+### Core Files
+
+-   **`src/server.js`**: The main entry point for the backend. It sets up the Express server, configures all middleware (including sessions and Passport), mounts the API and authentication routes, and starts the server.
+
+### Middleware (`src/middleware/`)
+
+Middleware functions are the backbone of the Express application, handling requests sequentially.
+
+-   **`session.js`**: Configures `express-session` to manage user sessions. It sets up session secrets, cookie properties, and timeouts. In a production environment, the default `MemoryStore` should be replaced with a more robust session store like Redis.
+-   **`passport.js`**: Configures the `passport-saml` strategy. It loads the IdP's signing certificate and defines the SAML configuration options, including the entry point (for login), logout URL, and callback URLs. It also maps the attributes from the SAML profile to a user object that is stored in the session.
+-   **`requireAuth.js`**: A simple middleware that protects routes by checking if a user is authenticated (`req.isAuthenticated()`). If the user is not logged in, it returns a 401 Unauthorized error for API requests or redirects to the login page for browser requests.
+
+### Routes (`src/routes/`)
+
+-   **`auth.js`**: Handles all authentication-related routes.
+    -   `/auth/login`: Initiates the SAML login flow by redirecting the user to the IdP.
+    -   `/auth/saml/callback`: The endpoint where the IdP posts the SAML assertion after a successful login. Passport processes the assertion and creates a user session.
+    -   `/auth/logout`: Initiates the SAML Single Log-Out (SLO) flow.
+    -   `/auth/logout/callback`: The endpoint where the IdP redirects the user after a successful logout.
+    -   `/auth/me`: An API endpoint for the frontend to check if the current user is authenticated and to get their user information.
+-   **`pages.js`**: Handles serving the main `index.html` file for different client-side URLs (e.g., `/` and `/settings`). This enables the single-page application to handle routing on the client side while still allowing users to directly navigate to or refresh pages. Routes in this file are protected by the `requireAuth` middleware where necessary.
+-   **`index.js`**: The main **API router**. It assembles all other API-related route files (like `timestamp.js` and `echo.js`) and is mounted under the `/api` prefix in `server.js`.
+-   **`timestamp.js`**, **`echo.js`**, etc.: Example API routes that demonstrate how to create authenticated endpoints that might communicate with other backend services.
+
+---
+
+## Frontend (`public/`)
+
+The frontend is a single-page application (SPA) built with modern, framework-less JavaScript. It uses Web Components to create encapsulated and reusable UI elements.
+
+### Core Files
+
+-   **`public/index.html`**: The main HTML file. It contains the basic page structure and a single custom element, `<biocbot-app>`, which is the root of the application.
+-   **`public/app.js`**: The main entry point for the frontend JavaScript. It imports all the Web Component classes and registers them with the browser using `customElements.define()`.
+
+### Components (`public/components/`)
+
+-   **`BiocbotApp/`**: The root component. It manages the application's core state, including the user's authentication status and which view (`<authenticated-view>` or `<settings-view>`) is currently active. It uses the browser's History API to handle client-side routing, updating the URL as the user navigates through the application.
+-   **`LoginPrompt/`**: A simple component shown to unauthenticated users. It displays a "Login" button that redirects the user to the `/auth/login` route to start the SAML flow.
+-   **`AuthenticatedView/`**: The main view for logged-in users. It displays user details, provides buttons to make authenticated API calls, and includes a link to the settings page.
+-   **`SettingsView/`**: A component that displays different content based on the user's affiliation (e.g., 'student' or 'faculty'). It demonstrates how to implement simple role-based access control on the frontend and includes a "Back" button to return to the main view.
+-   **`ResponseDisplay/`**: A utility component used to format and display the JSON responses from the backend API calls.
+
+## Getting Started
+
+1.  **Clone the repository.**
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+3.  **Set up your environment:**
+    -   Copy the `.env.example` file to a new file named `.env`.
+    -   Update the variables in `.env` to match your local development environment.
+4.  **Run the application:**
+    ```bash
+    npm start
+    ```
+5.  Open your browser and navigate to the URL specified by the `PORT` in your `.env` file (e.g., `http://localhost:8050`).

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "tlef-biocbot",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.10.0",
+    "dotenv": "^16.5.0",
+    "express": "^5.1.0",
+    "express-session": "^1.18.1",
+    "passport": "^0.7.0",
+    "passport-saml": "^3.2.4"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.10"
+  }
+}

public/app.js

@@ -0,0 +1,30 @@
+/**
+ * BIOCBOT Frontend Component Registrar
+ *
+ * This file is the main entry point for the frontend application. Its primary
+ * responsibility is to define all the custom elements (Web Components) used in
+ * the application, effectively telling the browser what class to instantiate
+ * for a given HTML tag (e.g., `<biocbot-app>`).
+ *
+ * The actual application logic (like checking auth status) is not triggered
+ * from this file. Instead, it's initiated by the `connectedCallback` lifecycle
+ * method within the components themselves (e.g., in BiocbotApp.js), which is
+ * the standard and best practice for component-based architectures.
+ */
+
+// Import the JavaScript class for each component.
+// The paths are relative to this file's location.
+import BiocbotApp from './components/BiocbotApp/BiocbotApp.js';
+import LoginPrompt from './components/LoginPrompt/LoginPrompt.js';
+import AuthenticatedView from './components/AuthenticatedView/AuthenticatedView.js';
+import ResponseDisplay from './components/ResponseDisplay/ResponseDisplay.js';
+import SettingsView from './components/SettingsView/SettingsView.js';
+
+// The `customElements.define()` method registers a new custom element with the browser.
+// The first argument is the HTML tag name for the element (which must contain a hyphen).
+// The second argument is the JavaScript class that controls its behavior.
+customElements.define('biocbot-app', BiocbotApp);
+customElements.define('login-prompt', LoginPrompt);
+customElements.define('authenticated-view', AuthenticatedView);
+customElements.define('response-display', ResponseDisplay);
+customElements.define('settings-view', SettingsView);