refactor: overhaul server and upgrade AuthC to v5 (#26)

* feat(api): add integrated OAS specification at /docs/api endpoint and improve documentation. 
* refactor(server): restructure/simplify API routes and frontend forms for maintainability and readability
* chore(deps): upgrade AuthC dependencies and server to version 5

Author: authcompanion

.gitignore

@@ -6,4 +6,5 @@ node_modules
 serverkey
 adminkey
 .DS_Store
-.idea
+.idea
+/client/dist

.vscode/extensions.json

@@ -4,7 +4,6 @@
 
 	// List of extensions which should be recommended for users of this workspace.
 	"recommendations": [
-		"humao.rest-client"
 	],
 	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
 	"unwantedRecommendations": [

Dockerfile

@@ -1,56 +1,51 @@
-FROM node:18-slim as builder
+# Stage 1: Builder stage (full build environment)
+FROM node:22-slim AS builder
 
 LABEL org.opencontainers.image.title="AuthCompanion"
-LABEL org.opencontainers.image.version="4.0.0-beta.1"
-LABEL org.opencontainers.image.description="An admin-friendly, User Management Server (with Passkeys & JWTs) - for seamless and secure integration of user authentication"
+LABEL org.opencontainers.image.version="5.0.0-beta.1"
+LABEL org.opencontainers.image.description="An admin-friendly, User Management Server (with Passkeys & JWTs)"
 LABEL org.opencontainers.image.authors="Paul Fischer"
 LABEL org.opencontainers.image.source=https://github.com/authcompanion/authcompanion2
 
-# update packages, to reduce risk of vulnerabilities
-RUN apt-get update && apt-get upgrade -y && apt-get autoclean -y && apt-get autoremove -y
+WORKDIR /app
 
-# set a non privileged user to use when running this image
-RUN groupadd -r nodejs && useradd -g nodejs -s /bin/bash -d /home/nodejs -m nodejs
-USER nodejs
-# set right (secure) folder permissions
-RUN mkdir -p /home/nodejs/app/node_modules /home/nodejs/app/authdata && chown -R nodejs:nodejs /home/nodejs/app
+# Copy package files first for caching
+COPY package*.json ./
+# Install all dependencies including devDependencies
+RUN npm install --include=dev
+# Copy all project files
+COPY . .
+# Build the application
+RUN npm run build
 
-WORKDIR /home/nodejs/app
+# Stage 2: Production stage (lean image)
+FROM node:22-slim
 
-# set default node env
-ARG NODE_ENV=production
-# ARG NODE_ENV=production
-# to be able to run tests (for example in CI), do not set production as environment
-ENV NODE_ENV=${NODE_ENV}
+# Create non-root user and set directory permissions
+RUN groupadd -r nodejs && \
+    useradd -g nodejs -s /bin/bash -d /home/nodejs -m nodejs && \
+    mkdir -p /home/nodejs/app && \
+    chown -R nodejs:nodejs /home/nodejs/app
 
-ENV NPM_CONFIG_LOGLEVEL=warn
+RUN mkdir -p /data && \
+    chown nodejs:nodejs /data && \
+    chmod 755 /data
 
-# copy project definition/dependencies files, for better reuse of layers
-COPY --chown=nodejs:nodejs package*.json ./
+WORKDIR /home/nodejs/app
 
-# install dependencies here, for better reuse of layers
-RUN npm install
+# Copy application files with correct ownership
+COPY --from=builder --chown=nodejs:nodejs /app .
 
-# copy all sources in the container (exclusions in .dockerignore file)
-COPY --chown=nodejs:nodejs . .
+# Set environment variables directly in Dockerfile
+ENV NODE_ENV=production
+ENV NPM_CONFIG_LOGLEVEL=warn
 
-# build/pack binaries from sources
+# Final cleanup
+RUN npm prune --omit=dev && \
+    npm cache clean --force
 
-# This results in a single layer image
-# FROM node:lts-alpine AS release
-# COPY --from=builder /dist /dist
+USER nodejs
 
-# exposed port/s
 EXPOSE 3002
 
-# add an healthcheck, useful
-# healthcheck with curl, but not recommended
-# HEALTHCHECK CMD curl --fail http://localhost:8000/health || exit 1
-# healthcheck by calling the additional script exposed by the plugin
-# HEALTHCHECK --interval=30s --timeout=10s --start-period=5s CMD npm run healthcheck-manual
-
-# ENTRYPOINT [ "node" ]
-# CMD [ "npm", "start" ]
-CMD [ "node", "server.js" ]
-
-# end.
+CMD [ "node", "server.js" ]

Dockerfile.arm64

@@ -1,54 +1,43 @@
-# Stage 1: Build the application
-FROM node:18-slim as builder
+# Stage 1: Builder stage
+FROM --platform=linux/arm64 node:22-slim AS builder
 
 LABEL org.opencontainers.image.title="AuthCompanion"
-LABEL org.opencontainers.image.version="4.0.0-beta.1"
-LABEL org.opencontainers.image.description="An admin-friendly, User Management Server (with Passkeys & JWTs) - for seamless and secure integration of user authentication"
+LABEL org.opencontainers.image.version="5.0.0-beta.1"
+LABEL org.opencontainers.image.description="An admin-friendly, User Management Server (with Passkeys & JWTs)"
 LABEL org.opencontainers.image.authors="Paul Fischer"
 LABEL org.opencontainers.image.source=https://github.com/authcompanion/authcompanion2
 
-# update packages, to reduce the risk of vulnerabilities
-RUN apt-get update && apt-get upgrade -y && apt-get autoclean -y && apt-get autoremove -y
+WORKDIR /app
 
-# set a non-privileged user to use when running this image
-RUN groupadd -r nodejs && useradd -g nodejs -s /bin/bash -d /home/nodejs -m nodejs
-USER nodejs
-# set the right (secure) folder permissions
-RUN mkdir -p /home/nodejs/app/node_modules /home/nodejs/app/authdata && chown -R nodejs:nodejs /home/nodejs/app
+COPY package*.json ./
+RUN npm install --include=dev
+COPY . .
+RUN npm run build
 
-WORKDIR /home/nodejs/app
+# Stage 2: Production stage
+FROM --platform=linux/arm64 node:22-slim
 
-# set default node env
-ARG NODE_ENV=production
-ENV NODE_ENV=${NODE_ENV}
+RUN groupadd -r nodejs && \
+    useradd -g nodejs -s /bin/bash -d /home/nodejs -m nodejs && \
+    mkdir -p /home/nodejs/app && \
+    chown -R nodejs:nodejs /home/nodejs/app
 
-ENV NPM_CONFIG_LOGLEVEL=warn
+RUN mkdir -p /data && \
+    chown nodejs:nodejs /data && \
+    chmod 755 /data
 
-# copy project definition/dependencies files, for better reuse of layers
-COPY --chown=nodejs:nodejs package*.json ./
-
-# install dependencies here, for better reuse of layers
-RUN npm install
+WORKDIR /home/nodejs/app
 
-# copy all sources in the container (exclusions in .dockerignore file)
-COPY --chown=nodejs:nodejs . .
+COPY --from=builder --chown=nodejs:nodejs /app .
 
-# Stage 2: Create a minimal image for ARM64v8
-FROM arm64v8/node:18-slim
+ENV NODE_ENV=production
+ENV NPM_CONFIG_LOGLEVEL=warn
 
-WORKDIR /home/nodejs/app
+RUN npm prune --omit=dev && \
+    npm cache clean --force
 
-# Copy the application files from the builder stage
-COPY --from=builder /home/nodejs/app .
+USER nodejs
 
-# Exposed port/s
 EXPOSE 3002
 
-# Add an healthcheck, useful
-# Healthcheck with curl, but not recommended
-# HEALTHCHECK CMD curl --fail http://localhost:8000/health || exit 1
-# Healthcheck by calling the additional script exposed by the plugin
-# HEALTHCHECK --interval=30s --timeout=10s --start-period=5s CMD npm run healthcheck-manual
-
-# Entrypoint and command
-CMD [ "node", "server.js" ]
+CMD [ "node", "server.js" ]

README.md

@@ -17,24 +17,22 @@
      <img alt="GitHub stars" src="https://img.shields.io/github/stars/authcompanion/authcompanion2">
    </a>
    <a href="https://nodejs.org/en/">
-     <img src="https://img.shields.io/badge/node-v20.11.0-green?logo=node.js"/>
+     <img src="https://img.shields.io/badge/node-v22-green?logo=node.js"/>
    </a>
       <a href="https://github.com/authcompanion/authcompanion2/tags">
      <img src="https://img.shields.io/github/v/release/authcompanion/authcompanion2?color=purple&include_prereleases&style=flat-square"/>
    </a>
 
 </div>
 <br />
-<p align="center"> Useful Links:  <a href="https://docs.authcompanion.com/"> Documentation</a> | <a href="https://github.com/authcompanion/authcompanion2/blob/main/CHANGELOG.md"> CHANGELOG</a> | <a href="https://demo.authcompanion.com/v1/web/login"> Demo Site</a> | <a rel="me" href="https://hachyderm.io/@paulfish"> Follow on Mastodon</a>
+<p align="center"> Useful Links:  <a href="https://docs.authcompanion.com/"> Documentation</a> | <a href="https://github.com/authcompanion/authcompanion2/blob/main/CHANGELOG.md"> CHANGELOG</a> | <a href="https://demo.authcompanion.com/login"> Demo Site</a> | <a rel="me" href="https://hachyderm.io/@paulfish"> Follow progress on Mastodon</a>
 </p>
 
 ---
 
 ## Hot topics
 
-- Our documentation now includes 2 new [.rest files](https://github.com/authcompanion/authcompanion2/tree/main/tools) that utilize the VS Code [REST Client plugin](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) to simplify API testing and provide clear examples of Authcompanion's admin and authentication APIs.
-- New Support for Postgres when storing user accounts + New Login & Registration Web Form Styling - [#22](https://github.com/authcompanion/authcompanion2/pull/22) [Done]
-- A Refresh of the Admin Dashboard Design - [#21](https://github.com/authcompanion/authcompanion2/pull/21) [Done]
+- We've added full OpenAPI 3.0 specification integration. Access the interactive documentation at: http://localhost:3002/docs/api when running the AuthC Server. Also refresh all of the site documentation for better clarity and instruction.
 
 ## Introduction
 
@@ -44,7 +42,7 @@ With AuthC you can:
 
 - Securely handle the registration, login, logout, and account recovery of user accounts.
 - Generate and verify [JWTs](https://jwt.io/introduction), a token used for your user's session and authenticating them into your web application's backend APIs.
-- Manage Users via a self-service Dashboard and confidently store and own your web application's user accounts, on your terms.
+- Manage users via a self-service Dashboard and confidently store and own your web application's user accounts, on premises.
 - Help users create accounts and login with a passkey on their mobile device (aka passwordless) or by using traditional username/passwords instead.
 
 |             Login Screen             |            Registration Screen             |
@@ -59,7 +57,7 @@ The instructions below will launch the default server for exploring the features
 
 Pre-requirement:
 
-- [Node.js](http://nodejs.org) **version >=18.13**
+- [Node.js](http://nodejs.org) **version >=22**
 
 Clone the repo if you haven't done so, and install dependencies using this
 command:
@@ -171,13 +169,12 @@ Have a look through the [Integration Guide](https://docs.authcompanion.com/guide
 
 The RESTful Authentication API powers the Web Forms by which users authenticate into your web app. It's important to note that the web forms alone doesn't cover every authentication flow for your users. For example: refreshing an expired access token would require interacting with AuthC's APIs in addition to using the Web Froms.
 
-For more information about the Authentication API check out the docs here: [Auth API](https://docs.authcompanion.com/guide/authapi.html)
-
 ### Admin API
 
 The Admin API helps an administrator to manage the users of their web application. It provides a range of functions through which administrators can programatially create, edit, and delete user accounts. The Admin API is also natively used by the Admin Dashboard.
 
-For more information about the Admin API check out the docs here: [Admin API](https://docs.authcompanion.com/guide/adminapi.html)
+- **Try the API:** Open [http://localhost:3002/docs/api](http://localhost:3002/docs/api) in your browser while the AuthC server is running.
+- **Interactive Documentation:** The documentation UI allows you to try endpoints, inspect request/response schemas, and view detailed requirements.
 
 ---