# DOLD Equivalent Finder: install on Heart Internet

Target address: **https://doldtools.co.uk/finder/**

This runs as a folder on a site you already host, so no subdomain is needed. The package works in any folder name. If you use a different site or folder, put your own address wherever this guide says `doldtools.co.uk/finder`.

The package has three parts:
- a static front end
- a small PHP API (`api/index.php`) that checks each user's Microsoft 365 sign-in
- a `private/` folder holding the product data and the Entra settings

Product data is only sent to users signed in to the DOLD Microsoft 365 tenant. Guest and personal Microsoft accounts are blocked.

Requirements:
- Linux hosting with PHP 7.4 or later (PHP 8.x recommended), with the openssl and curl extensions. Both are standard on Heart.
- Apache `.htaccess` support, which is also standard.
- HTTPS on the site. Microsoft sign-in will not work over plain http. If `https://doldtools.co.uk` does not already load with a padlock, issue the free SSL certificate for doldtools.co.uk in the Heart control panel under SSL Certificates first.

## 1. Upload the files
1. Unzip `dold-finder-heart.zip`. Inside is a folder called `finder`.
2. Connect by FTP or SFTP (FileZilla is fine) to the doldtools.co.uk hosting. Open the site's web folder, usually `public_html`.
3. Upload the whole **`finder`** folder into `public_html`. The result should be `public_html/finder/index.html`.
4. Make sure the hidden files `finder/.htaccess` and `finder/private/.htaccess` were uploaded. In FileZilla, turn on **Server > Force showing hidden files** to check.
5. Upload `finder/private/products.json` in **binary** mode. It is about 4.4 MB.

The resulting layout:
```
public_html/
  (your existing site files - untouched)
  finder/
    .htaccess
    index.html, app.js, auth.js, styles.css, redirect.html
    vendor/msal-browser.min.js
    api/index.php
    private/.htaccess, config.php, products.json
```

The finder has its own `.htaccess`, so it does not affect the rest of your site, and your site's rules do not affect the finder. That includes WordPress.

Optional extra hardening: move the `private` folder **outside** `public_html`, and rename it to `finder-private` so it sits next to `public_html`. The API looks there first, then falls back to `finder/private`.

The `private` folder must be writable by PHP, which it is by default on Heart. The API stores a small cache of Microsoft's signing keys there.

## 2. Register the sign-in addresses in Microsoft Entra
Go to Entra admin centre > **App registrations** > the finder app (client ID `6bcfc4fd-070b-4c73-ab0e-0bbbe426d7f1`) > **Authentication**. Under **Single-page application**, add these redirect URIs:

- `https://doldtools.co.uk/finder/`
- `https://doldtools.co.uk/finder/redirect.html`

If your site also answers on `www.`, add these two as well:
- `https://www.doldtools.co.uk/finder/`
- `https://www.doldtools.co.uk/finder/redirect.html`

Save. You can remove the old `dold-equivalent-finder.pplx.app` addresses once the new site works.

## 3. Check it
| Open | Expected |
|---|---|
| https://doldtools.co.uk/finder/api/health | `{"ok":true}` |
| https://doldtools.co.uk/finder/api/auth-config | `"configured":true` |
| https://doldtools.co.uk/finder/api/products | `{"error":"sign_in_required"}` |
| https://doldtools.co.uk/finder/private/products.json | 403 Forbidden |
| https://doldtools.co.uk/finder/ | Microsoft sign-in screen, then the finder |

Troubleshooting:
- **AADSTS50011 (redirect URI mismatch):** the address in the browser bar does not match step 2 exactly. Check `www.` and the trailing `/`.
- **"invalid_token" after signing in:** the hosting may be stripping the Authorization header. The `.htaccess` already passes it through. If it still fails, ask Heart support to allow `HTTP_AUTHORIZATION` for PHP.
- **/finder/api/health shows 404 or your site's own error page:** `finder/.htaccess` was not uploaded, or mod_rewrite is off.
- **The page loads but stays on "Checking sign-in":** open the browser console. All files in `vendor/` must be uploaded.

## Restricting access further
Edit `private/config.php`:
- `'allowedDomains' => ['dold.co.uk']` admits only addresses on that domain.
- `'allowedEmails' => ['ian@dold.co.uk', ...]` admits only named users.

Alternatively, in Entra go to Enterprise applications > the app > Properties and set **Assignment required = Yes**, then assign users or groups.

## Updating the product data
Replace `private/products.json` by FTP. The API rebuilds its compressed copy (`products.json.gz`) automatically.