Installation guide

​

Prerequisites

• Bun ≥ 1.3 (tested with 1.3.14). Bun is the only requirement — no Node.js, no database server, no Docker, no cloud credentials for the local path.

curl -fsSL https://bun.sh/install | bash

​

Local installation

git clone https://github.com/clarkdickens/FindMyData.git FindMyData
cd FindMyData
bun install          # install workspace dependencies
bun run seed         # create + migrate the dev database and seed the demo org
bun run dev          # start API (http://localhost:8710) + web (http://localhost:5173)

• GET http://localhost:8710/api/health → {"status":"ok"}
• GET http://localhost:8710/api/ready → readiness plus per-integration modes (see Readiness and honest integration modes)

rm -rf packages/server/data && bun run seed

​

Seed guards

• Exits with an error if FMD_ENV is not development.
• Exits with an error if the database already contains a tenant — it never overwrites. Delete the data directory to reseed.

​

What bun run seed creates

• Tenant + org profile (industries Retail/Logistics; geographies United States/European Union) and an uploaded governance policy document.
• A sensitivity-label catalog fixture.
• An AI-generated taxonomy draft (deterministic mock AI provider), then governance-approved Human Resources and Finance business domains with owners assigned.
• A mock Microsoft 365 connector instance (Microsoft 365 (deterministic fixture)), discovered source scopes (the HR screening drive is marked as HR’s expected/authoritative location), and a completed baseline inventory scan of every scope through the real durable pipeline.

​

Configuration reference

​

Secret-reference indirection (*_REF)

FMD_GRAPH_CLIENT_SECRET_REF=GRAPH_CLIENT_SECRET   # points at the env var below
GRAPH_CLIENT_SECRET=<the actual secret>            # e.g. injected from Key Vault

​

Core

​

Object store

​

Connector mode

​

Microsoft Graph identifiers and secret references

​

Entra OIDC sign-in

​

AI provider

​

Webhook public URL

​

Exchange mailboxes

​

Control plane entitlement (licensing)

​

Feature flags

​

Production boot lockouts

1. Dev auth is refused. FMD_AUTH_MODE=dev fails with: FATAL: FMD_AUTH_MODE=dev is not permitted when FMD_ENV=production. Configure FMD_AUTH_MODE=entra with a valid Entra application.
2. The default session secret is refused. FMD_SESSION_SECRET=dev-only-change-me (or unset, which yields the default) fails with: FATAL: default FMD_SESSION_SECRET is not permitted when FMD_ENV=production.

​

Worker topology: embedded vs. standalone

• Embedded (default). bun run dev / the API process (packages/server/src/main.ts) starts a worker loop in-process (worker ID embedded-<pid>). The embedded worker also owns the periodic sweep: renewing due change-notification subscriptions, stamping reconcile freshness, and expiring unrenewable subscriptions.
• Standalone (optional). bun run worker runs packages/server/src/worker-main.ts as a separate process (worker ID worker-<pid>) against the same database and queue, with graceful SIGINT/SIGTERM shutdown. Use it to scale scanning independently of the API; multiple workers can pull from the shared queue. Note the standalone worker does not run the subscription sweep — that stays with the embedded worker in the API process.

​

Readiness and honest integration modes

• mock — deterministic fixture path (exercised by tests).
• live — the feature is enabled and its credentials actually resolve (the *_REF points at a present value), not merely configured.
• blocked — configured or enabled but a prerequisite is unmet. Never silently faked.
• disabled — not enabled.

​

Feature-gate matrix

​

Azure deployment

# 1. Validate the template
az bicep build --file infra/main.bicep

# 2. Fill in infra/main.bicepparam (non-secret identifiers only)

# 3. Deploy
az deployment group create -g <rg> -f infra/main.bicep -p infra/main.bicepparam

# 4. Set secret values out-of-band (never committed; Key Vault names:
#    fmd-session-secret, fmd-graph-client-secret)

# 5. Restart the Container App to pick them up

• No secrets in source control. Key Vault secrets are placeholders set out-of-band; the app reads them through Key-Vault-backed Container App secrets resolved by managed identity. The *_REF indirection is preserved: the template sets FMD_GRAPH_CLIENT_SECRET_REF=GRAPH_CLIENT_SECRET and binds GRAPH_CLIENT_SECRET to the Key Vault secret.
• Production lockout active. The template sets FMD_ENV=production and FMD_AUTH_MODE=entra; the app refuses to boot with dev auth or the default session secret.
• Honest scale posture. The template provisions the zero-dependency SQLite-on-file-share default with the worker embedded in the API replica. The application’s optional PostgreSQL 16 backend is built and load-validated (FMD_DB_BACKEND=postgres, 2M assets), but this template deliberately does not provision managed PostgreSQL, a separate worker Container App, private endpoints, or Azure OpenAI — configure those separately when you need them; see infra/README.md and ADR-0003.

​

Operator validation (Entra OIDC + Sites.Selected)

​

Entra OIDC sign-in

1. Register a sign-in app. In Entra ID → App registrations, create a new registration (confidential web app). Add a Web redirect URI equal to https://<your-host>/api/auth/entra/callback — it must match FMD_ENTRA_REDIRECT_URI exactly. Add a client secret and store its value in your secret store, not in source.
2. Delegated permissions. Add the delegated Microsoft Graph scopes openid, profile, email and grant admin consent. No application permissions are needed for sign-in (those belong to the separate Graph read/scan app).
3. Configure the deployment. Set FMD_AUTH_MODE=entra, FMD_ENTRA_TENANT_ID, FMD_ENTRA_CLIENT_ID, FMD_ENTRA_CLIENT_SECRET_REF (pointing at the env var that holds the secret), and FMD_ENTRA_REDIRECT_URI. For a national cloud also set FMD_ENTRA_LOGIN_HOST. Ensure FMD_SESSION_SECRET is a real non-default value.
4. Pre-provision the first user. Because identity binds by (issuer, subject) and never by email, create the internal principal(s) with each person’s directory object id (oid) as external_id before they sign in (or set FMD_ENTRA_AUTO_PROVISION=true to JIT-create a role-less principal, then grant capability). An unrecognized, non-provisioned user is refused with identity_not_provisioned.
5. Confirm it is live. GET /api/ready should report integrations.entraSignIn: "live". Visit /api/auth/entra/login — you should be redirected to your tenant’s consent/sign-in, and after signing in land back authenticated with a session cookie. A failed sign-in redirects to /?login_error=<code> (and logs entra_login_failed with a correlation id) — never a silent dev fallback.

​

Sites.Selected (least-privilege SharePoint)

1. Consent Sites.Selected. On the Graph read/scan app registration, add the application permission Sites.Selected and grant admin consent. By itself it grants access to nothing.
2. Grant the specific sites. For each site to scan, grant the app read (or write for remediation) via POST /sites/{id}/permissions or admin tooling. Record each site’s identifier.
3. List them. Set FMD_SP_SITES to the comma-separated site path identifiers, each {host}:/sites/{name} (not the composite {host},{coll}, {site} id — it contains commas and would be split apart).
4. Confirm least privilege. Run discovery; only the listed sites resolve, and the tenant-wide search=* enumeration is never issued. A site whose grant hasn’t propagated (403/404) is skipped, not fatal. De-selection is enforced at scan time: removing a site from FMD_SP_SITES blocks its persisted drive at the next scan and drains it on re-register. Leaving FMD_SP_SITES empty keeps the broader Sites.Read.All pilot behavior; a value that reduces to no valid entries refuses to boot rather than silently scanning the whole tenant.

​

Gated live connectors (Graph read, Purview, Teams/Exchange, storage, SQL, Drive, Box)

​

Related documentation

• STATUS.md — implemented / mocked / gated honesty ledger
• Architecture and ADRs
• Permissions manifest — Microsoft Graph permissions and protected-API notes
• Threat model · Capacity model · Roadmap