CJG Hub Bridge 1.0.1 — 23rd October 2026

This package contains only CJG-authored source. WHMCS proprietary software,
Odoo core, OCA add-ons, private configuration, databases and customer data are
not included. CJG-authored bridge code is AGPL-3.0-or-later; see LICENSE.

Ownership
The Portal owns every customer account, hosted service, invoice, payment,
support ticket and Tech Over Tea booking/ledger decision. Hub imports read-only
projections and creates managed Field Service work/private calendar entries.
Only confirmed/completed bookings occupy calendar time. The internal organiser
is the sole attendee; the bridge sends no invitations or reminders. Ledger
minutes are copied from the existing add-on, never calculated or posted here.
The invoice balance comes from the native GetInvoice API.

Installation and configuration
Install whmcs/modules/addons/cjg_hub_bridge in the Portal add-ons directory and
odoo/cjg_portal_bridge on Odoo's custom add-ons path. Do not modify core files.
The Odoo module depends on cjg_hub, fieldservice, calendar and sign_oca.
Activate the Portal add-on using its native module activation/configuration;
grant only the authorised admin role. Install the Odoo module, grant the CJG
connection manager group only to the intended staff user, and configure the
private files before enabling cjg_portal_bridge.cron_sync (every five minutes).

Portal config: /etc/cjg-hub-bridge/portal.chrystopherjames.group.json
Hub config: /run/cjg-bridge/config.json (read-only container bind mount).
Keys: enabled, hub_url, portal_url, admin_path, staff_map, inbound_key,
outbound_key. Use two independent random 64-character hex keys, reversed at
the other end; never store keys in the add-on, web root, repository or logs.
The production map is Portal admin 1 -> Hub user 2; additional users require an
explicit reviewed map. Internal users retain their existing native permissions.

Authentication
The two origins bind their own browser states. Codes are hashed at rest,
short-lived and atomically single-use. TLS and directional HMAC signatures bind
method, path, timestamp, nonce and exact body; successful requests cannot replay.
Normal passwords are unchanged. Native Hub session.authenticate and the native
Portal admin form perform authentication and preserve their MFA stages. Customer
hand-offs require the owning, active Portal account with SSO allowed; they only
open the exact agreement for that account. Hub customer action identities cannot
use independent password sign-in/reset. Native private signing links still work.
Customer return uses CreateSsoToken only after a fresh verified Portal identity.
Do not replace these flows with manual session assignment or email matching.
Public customer registration goes to the Portal. Valid private invitations for
existing internal Hub staff retain the native staff setup flow.

Operations and recovery
The Customers app contains the overview and Connection status. Source changes
queue in mod_cjg_hub_changes; complete paged reconciliation also runs regularly,
including Tech Over Tea objects. Retries use stable source IDs and hashes. Missing
source objects become inactive history. Connection failures retain the previous
verified data and show an error/freshness indicator. WHMCS support, Ziverly and
Tech Over Tea source files/hooks are not modified by this module.

Disable the Hub refresh cron and deactivate the Portal add-on to stop the bridge.
Deactivation retains own history and never deletes native business records.
Restore database and filestore together for Hub recovery. Keep private configs
and signing keys in restricted server backups, separate from public source.
For an upgrade, snapshot both systems; restore an isolated Hub copy; install/
upgrade the module there; run the transport, permissions, authentication and
visit-transition checks; inspect browser assets and navigation before live use.
No compatibility with an untested future major Odoo/WHMCS version is promised.

Validation supplied in tests/
php-test.php: PHP transport/store/projection allowlists and replay tests.
projection-checks.py: run with Odoo shell in an isolated copy; rolls back fixtures.
HTTP authentication scripts are deployment checks requiring the private config;
they must never print codes, tokens or credentials. They exercise native staff
and customer hand-offs, browser binding, replay and account separation.

Documentation
https://developers.whmcs.com/hooks-reference/admin-area/#authadmin
https://developers.whmcs.com/api-reference/createssotoken/
https://developers.whmcs.com/advanced/authentication/
