AngularPort

An independently maintained Angular 22 frontend for Apache Guacamole 1.6.0, with a checksummed browser-runtime manifest whose 91 files are bound to a recorded real-stack acceptance run.

The goal is narrow and reviewable: replace the stock Guacamole 1.6.0 webapp assets with an Angular frontend that speaks the same REST, WebSocket and HTTP-tunnel endpoints, while retaining the stock backend, database schema and protocol libraries. This is not an official Apache Guacamole release and is not affiliated with or endorsed by the Apache Software Foundation.

Reproducible release evidence

The public verification gate requires:

• 37 required acceptance cases, zero failures, zero blocked cases, against a real Guacamole 1.6.0 stack (guacd, PostgreSQL 16, SSH/SFTP, VNC and xrdp fixtures)
• 218 unit tests across 28 spec files
• 46 dist smoke checks against the production build
• a strict 30-minute two-session soak: 33 fully measured cycles, zero undelivered inputs, zero uncaught errors, zero sessions after logout
• 91 browser-runtime files matching the published runtime manifest fc3bba5785fc18c82a7d3982e16e3b90c4fe5bef52339b344edb9525d55323ba
• first-time TOTP enrollment exercised through the shipped UI (QR + manual key read from the rendered interface), and HTTPS under normal certificate validation in an isolated trust store with no certificate-error suppression flags
• npm audit: zero findings in the shipped dependency set

The release asset is the approved prebuilt ZIP with a published SHA-256; GitHub's automatically generated source archives are not the release artifact. Supplied real-stack acceptance records report these results; separate reviews checked the evidence, the regression logic and the runtime identity, and their controlled probes are not independent live integration runs. See the scope, the acceptance record and the delivery notes.

Staging warning. The included staging environment is disposable test infrastructure only, not a production deployment recommendation. Its pinned historical images carry nonzero package-scan findings; production operators must select patched images and validate their own deployment.

Supported scope

Stable Angular frontend for the Guacamole 1.6.0 configurations documented in docs/STABLE-SCOPE.md. Independent, unofficial project with documented compatibility exclusions. The included staging environment is disposable test infrastructure, not a production deployment recommendation.

Supported: PostgreSQL authentication and TOTP (including first-time enrollment through the UI); Chrome/Chromium; Linux SSH/SFTP, VNC and xrdp fixtures; origin-root and /guacamole/ deployments; TLS and HTTP-tunnel fallback; the documented administration, sharing, transfer and preference workflows.

Not covered: other databases and authentication providers, general Windows RDP deployments, mobile and other browsers, warm-cache upgrades, accessibility conformance, arbitrary extension injection, and the documented advanced-feature exclusions.

Modernized stack

Area	Upstream baseline	This repository
Frontend framework	AngularJS 1.x	Angular 22.1.6 (standalone components, signals)
Build	Webpack 4 bundle	Angular CLI (esbuild) production build in dist/
Language	ES5 JavaScript	TypeScript with strict app and spec type checks
Protocol client	guacamole-common-js	the same vendored Apache Guacamole 1.6.0 modules (35 files), loaded unmodified
TOTP enrollment	extension-injected client template	native Angular enrollment renderer (server QR code, grouped manual key, instructions)
On-screen keyboard	stock OSK stylesheet	the same Apache-licensed OSK stylesheet, vendored as a global style
Runtime dependencies	browser globals	buffer polyfill for the import page; no other added runtime dependency

Specific behavior and security changes

• Login fields carry id="login-field-<name>"; the name attribute is consumed by Angular's NgModel, so external tooling should use the id.
• First-time TOTP enrollment is rendered natively from the server challenge (QR data URI, grouped manual key, digits, algorithm, interval) with readable instructions; arbitrary extension JavaScript injection remains excluded.
• The authentication token is sent as Guacamole-Token for REST requests and as a query parameter for tunnel and stream URLs, as the protocol requires; reserved query parameters such as token are never submitted as credentials.
• Share links carry the credential field the server advertises (the read-only profile's key query parameter); exported acceptance evidence records only a fingerprint.
• Uploads above a configured reverse-proxy limit are surfaced as errors, never silently truncated; deployments must configure the proxy request-size limit (the upstream manual documents this caveat).
• Acceptance TLS uses an isolated test trust store with normal certificate chain, hostname and validity validation; no certificate-error suppression flags are used.

These controls do not amount to a blanket security certification. See SECURITY.md and the staging warning above.

Requirements

• Node.js in the range declared by engines in package.json (^22.22.2 || ^24.15.0 || >=26.0.0); the build deliberately does not patch or bypass Angular CLI's runtime check.
• npm (bundled with Node).
• Chrome/Chromium for the dist smoke browser checks (optional; those checks skip honestly without a browser).
• Docker for the disposable staging acceptance stack (not required to build or unit-test the frontend).

Build and verify

npm ci
npx tsc -p tsconfig.app.json --noEmit
npx tsc -p tsconfig.spec.json --noEmit
npm run build
npm test -- --watch=false
npm run smoke
node scripts/runtime-manifest.mjs dist/angular-port/browser runtime-manifest.json

The production bundle is written to dist/angular-port/browser/. The <base href="./"> is relative, so the artifact deploys at the origin root or under a subpath such as /guacamole/ with the backend reachable under the same prefix.

Local staging setup (disposable)

./scripts/staging-up.ps1 -RebuildTargets   # stock Guacamole 1.6.0, guacd, PostgreSQL, targets
node tests/e2e/setup-backend.mjs           # fixtures through the real REST API
node tests/e2e/acceptance.mjs A            # acceptance groups A-H
node tests/e2e/soak.mjs                    # strict two-session soak
./scripts/staging-down.ps1                 # teardown

All published staging ports bind to loopback. See docs/STABLE-ACCEPTANCE.md for the case register and docs/DELIVERY.md for deployment and rollback notes.

Development server

npm run start

Then open http://localhost:4200/. To exercise a real backend, proxy at least /api, /tunnel, /websocket-tunnel and /translations to the Guacamole server.

Production configuration

• Serve dist/angular-port/browser/ same-origin behind a Guacamole 1.6.0 backend (swap into the webapp folder served by the backend or a reverse proxy).
• Proxy the REST, WebSocket and HTTP-tunnel endpoints; disable buffering for the streaming tunnel and allow the upload request size used by the client.
• The app fetches translations/<lang>.json at runtime; this repository's translation files include the TOTP extension keys so the enrollment UI is readable without server-side merging.
• No server-side component ships with this frontend. The backend, guacd and database remain stock Guacamole 1.6.0 components that operators must patch and validate for their deployment.

Compatibility notes

• Endpoint and protocol behavior targets stock Guacamole 1.6.0; the documented exclusions and deviations live in docs/STABLE-SCOPE.md, docs/PARITY.md and docs/DELIVERY.md.
• Check the documented scope against your deployment before replacing an existing frontend, and report issues through this repository's issue tracker.

Attribution and development disclosure

This repository is a derivative work of Apache Guacamole, originally distributed under the Apache License 2.0. Upstream notices are preserved, and the port's modifications use the same license. See NOTICE and LICENSE. Apache Guacamole is a trademark of the Apache Software Foundation; this project is unofficial and not endorsed by Apache.

The port was implemented with AI-assisted engineering under human direction. Release claims are limited to reproducible public checks and independent review; deployment-specific testing and operator judgment remain necessary.

Modernization services

SovNode helps teams modernize production web frontends and migrate legacy web applications to supported frameworks. Engagements can include compatibility assessment, implementation, security review, test recovery and runtime validation.

For a private assessment, contact admin1@sovnode.ai.