diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml new file mode 100644 index 0000000..796b9d5 --- /dev/null +++ b/.github/workflows/docs-link-check.yml @@ -0,0 +1,30 @@ +name: docs-link-check +on: + pull_request: + paths: + - '**.md' + - 'docs/**' + push: + branches: [main, master] + paths: + - '**.md' + - 'docs/**' + +permissions: + contents: read + +jobs: + link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Markdown link check + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --no-progress + --exclude-loopback + --exclude '^https://www\.gartner\.com/' + --exclude '^https://www\.wolterskluwer\.com/' + '**/*.md' + fail: true diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..2bd5a0a --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +22 diff --git a/AGENTS.md b/AGENTS.md index 297445f..1f46b25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,11 @@ ## Merge / handoff verification bar -Run in order (fix failures before merge or handoff): - ```bash ./scripts/verify.sh -npm run verify ``` -`./scripts/verify.sh` is the harness Definition of Done wrapper; it delegates to `npm run verify`. -Defined as: **`eslint` → `tsc --noEmit` → `vitest run`**. Same as CI `verify` job (without Playwright). +Harness Definition of Done — delegates to `npm run verify` (`eslint` → `tsc --noEmit` → `vitest run`). Same as CI `verify` job (without Playwright). **Enterprise / technical diligence:** keep [docs/architecture-map.md](docs/architecture-map.md), [docs/workflow-depth.md](docs/workflow-depth.md), [docs/procurement-readiness.md](docs/procurement-readiness.md), and [docs/approval-workflow.md](docs/approval-workflow.md) aligned with real behavior when you change workflows, RBAC, retention, approvals, or integrations. Documentation index: [docs/README.md](docs/README.md); source tree: [docs/codebase-layout.md](docs/codebase-layout.md). For **staging / business UAT**, use [docs/qa/staging-uat-desk-to-field.md](docs/qa/staging-uat-desk-to-field.md); for **transactional `writeAuditLog` completeness**, maintain [docs/qa/mutation-auditability-matrix.md](docs/qa/mutation-auditability-matrix.md) when adding regulated mutations. After large router or delegation refactors, run **`npm run audit:matrix-greps`** (`scripts/audit-matrix-greps.sh`; **ripgrep** preferred, `find`+`grep` fallback) and refresh the matrix prose if counts shift. **Cursor MCP vs ship path:** contributors using IDE tool connections should follow [docs/cursor-tool-connections-deployment.md](docs/cursor-tool-connections-deployment.md) so staging/prod stay GitHub-/Vercel-/EKS-authoritative—not MCP-authoritative. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4954959..b78c5f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,7 @@ ### Bug Fixes -* **security:** per-org inbound secrets and SSRF-safe operational webhooks ([#39](https://github.com/SafetyMP/Autonomous-EHS-Management/issues/39)) ([f02e882](https://github.com/SafetyMP/Autonomous-EHS-Management/commit/f02e88233603c7ed4b76a051885ce66229e638e7)), closes [hi#severity](https://github.com/hi/issues/severity) +* **security:** per-org inbound secrets and SSRF-safe operational webhooks ([#39](https://github.com/SafetyMP/Autonomous-EHS-Management/issues/39)) ([f02e882](https://github.com/SafetyMP/Autonomous-EHS-Management/commit/f02e88233603c7ed4b76a051885ce66229e638e7)) ## [1.4.2](https://github.com/SafetyMP/Autonomous-EHS-Management/compare/v1.4.1...v1.4.2) (2026-07-06) diff --git a/Dockerfile b/Dockerfile index 4ca2755..d0d27f4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -32,7 +32,7 @@ # env at runtime → ConfigMap + Secret (never commit raw Secret YAML with data) # ============================================================================= -FROM node:26-bookworm-slim AS base +FROM node:22-bookworm-slim AS base WORKDIR /app # Disable Next telemetry in CI/images unless org policy wants it. ENV NEXT_TELEMETRY_DISABLED=1 diff --git a/README.md b/README.md index c4ca53a..688506d 100644 --- a/README.md +++ b/README.md @@ -48,13 +48,15 @@ ## Quick start +**Prerequisites:** Node.js **22.x** (see `.nvmrc`), npm, Docker (for demo Postgres). Matches CI and the production `Dockerfile`. + 1. **Clone and install:** `git clone && cd && npm ci` **Path tip:** Avoid a **working directory name with a trailing space** (some macOS / archive flows introduce `"…System "`). That can break scripts, tooling, and shell `cd` unless you always **quote paths**—prefer renaming the folder to remove stray spaces. 2. **Configure:** pick a row in **Environment snapshots** below and copy the listed template to `.env.local` (fill secrets). 3. **Run:** - **Docker demo:** `npm run demo:up` then `npm run dev` → [http://localhost:3000/sign-in](http://localhost:3000/sign-in) (details in [Turnkey local demo](#turnkey-local-demo-docker-postgres)). - **Your own Postgres:** `npm run db:migrate` then `SEED_ADMIN_EMAIL=you@company.com npm run db:seed` then `npm run dev`. -4. **Before a PR:** `npm run verify` — same bar as CI ([AGENTS.md](AGENTS.md)). +4. **Before a PR:** `./scripts/verify.sh` — harness DoD wrapper (same bar as `npm run verify` in CI). See [AGENTS.md](AGENTS.md). ## Environment snapshots diff --git a/docs/cursor-tool-connections-deployment.md b/docs/cursor-tool-connections-deployment.md index f815f5f..266d414 100644 --- a/docs/cursor-tool-connections-deployment.md +++ b/docs/cursor-tool-connections-deployment.md @@ -73,4 +73,4 @@ Branch/preview URLs must avoid pointing at production `DATABASE_URL`. Treat prev ## Related documentation - [procurement-readiness.md — customer vs internal Cursor tooling](./procurement-readiness.md#customer-facing-integrations-vs-internal-cursor-tooling) -- [REPO_SETUP.md § 10 Cursor IDE](./REPO_SETUP.md#10-cursor-ide-tool-connections-optional) +- [REPO_SETUP.md § 11 Cursor IDE](../REPO_SETUP.md#11-cursor-ide-tool-connections-optional) diff --git a/docs/procurement-readiness.md b/docs/procurement-readiness.md index 74d6675..1f9b01d 100644 --- a/docs/procurement-readiness.md +++ b/docs/procurement-readiness.md @@ -1,6 +1,6 @@ # Procurement readiness (strategy Pack) -This document implements the **business and GTM** recommendations from the critique Pack at repo root: [`Autonomous Ehs Management Recommendations.pdf`](../Autonomous%20Ehs%20Management%20Recommendations.pdf). +This document implements the **business and GTM** recommendations from the internal critique Pack (strategy PDF; not shipped in the public repo). It covers: ROI framing, pilot structure, economic moat narrative, implementation methodology, and repository presentation—**without** overstating shipped product scope. @@ -158,7 +158,7 @@ Use this in **enterprise questionnaires** so buyers do not assume filing-ready a |-----------------|---------------|-------------------------| | **OSHA agency-formatted electronic filing** | **`compliance.regulatoryOsha.agencyExportPlaceholder` only** — not submission-ready ([`ROADMAP.md`](../ROADMAP.md) barriers, [`oshaAgencyExportScaffold.ts`](../src/lib/regulatory/oshaAgencyExportScaffold.ts)). | Program data and internal injury/illness exports may be available; **direct agency submission formats** require counsel review and additional product work. | | **Full DSAR automation** | Intake / policy surfaces exist; end-to-end export/erasure needs **counsel process** ([`ROADMAP.md`](../ROADMAP.md)). | Privacy tooling is **governance-aligned**, not a one-click “erase everything” guarantee. | -| **Turnkey HRIS / Workday connector** | **iPaaS playbooks ship** ([`docs/runbooks/`](../runbooks/)); named vendor OAuth modules remain roadmap. Plan Workato/Boomi middleware + SCIM for PortCo pilots. Budget worksheet: [procurement-portco-integration-budget.md](./procurement-portco-integration-budget.md). | +| **Turnkey HRIS / Workday connector** | **iPaaS playbooks ship** ([`docs/runbooks/`](./runbooks/)); named vendor OAuth modules remain roadmap. Plan Workato/Boomi middleware + SCIM for PortCo pilots. Budget worksheet: [procurement-portco-integration-budget.md](./procurement-portco-integration-budget.md). | | **Customer MCP server** | **Context Sync REST** ships; native MCP server **does not** ([adr/0001-mcp-context-sync-strategy.md](./adr/0001-mcp-context-sync-strategy.md)). | Agent read access is **governed REST**, not MCP-branded; Cursor MCP is **internal dev tooling only**. | | **Occupational health clinic depth** | Not targeted at Cority-class medical surveillance in v1. | Occupational health programs may need a **specialist module** or partner system. | | **Environmental regulatory permits vs PTW** | **Permits to work** (`/dashboard/permits`) are **field authorization** (PTW). **Environmental permits** (`/dashboard/environmental-permits`) are a **regulatory register** (metadata, renewals, conditions)—**not** agency filing-ready by default (see [COMPLIANCE.md](../COMPLIANCE.md)). | Buyers should map **Cority/Enablon-style** permit tracking to the environmental permit module + obligations/monitoring; **do not** conflate with PTW. | diff --git a/docs/user-manual-ehs-console.md b/docs/user-manual-ehs-console.md index 67cac33..172d6f6 100644 --- a/docs/user-manual-ehs-console.md +++ b/docs/user-manual-ehs-console.md @@ -242,7 +242,7 @@ Desk supervisors still see program **Needs attention** chips and KPI tiles; desk 3. Optional: tap **Download command center CSV** (when the snapshot has loaded) to save the command-center figures your account may export—useful for leadership packs or audits. 4. When data loads, note **Snapshot as of** *date/time* under the header (if shown)—figures reflect that moment. 5. If **Needs attention:** appears, read the amber pill links for program-level alerts (personal approvals are deduplicated when shown in **Your work**). -6. Integration backlog and scheduled job health moved to **[Integrations](/dashboard/integrations)** for administrators. Supervisors may also see a **PortCo pilot proof** panel summarizing integration health when your organization runs a portfolio pilot—details live on **Integrations**, not on the desk home. +6. Integration backlog and scheduled job health moved to **Integrations** (`/dashboard/integrations`) for administrators. Supervisors may also see a **PortCo pilot proof** panel summarizing integration health when your organization runs a portfolio pilot—details live on **Integrations**, not on the desk home. 7. Under **Key indicators**, scan tiles (supervisors see the full grid; contributors may see them collapsed). Integration and cron panels no longer appear on the desk home. 8. Open **Recent activity** for a timestamped feed; links open record detail. 9. Expand **ISO setup checklist** in the sidebar panel when aligning the management system. @@ -1110,8 +1110,8 @@ Identity administrators, integration engineers, anyone granted **integration:rea ### SOP — Check status 1. Open **Integrations**. Heading **Integrations**. Intro text explains events are readable with **`integration:read`** and points to NDJSON warehouse export—the following paragraphs list inbound URLs, bearer secrets, and doc paths for administrators. -2. **PortCo identity (SCIM & OIDC JIT)** — when your role includes org admin controls, configure **SCIM 2.0** bearer tokens and **group→role mappings**, or **OIDC JIT claim rules** for multi-entity portfolios. Rotate tokens when counsel or IdP policy requires it. Engineering detail: [OIDC_JIT_PROVISIONING.md](../OIDC_JIT_PROVISIONING.md), [hris-portco-integration-playbook.md](../roadmap/hris-portco-integration-playbook.md). -3. **HRIS platform & roster drift** — copy the **inbound URL** and **bearer secret** for iPaaS connectors; pick connector presets (Workday, ADP, BambooHR) when shown. Review **Roster drift** rows after nightly reconciliation; use **Reconcile now** when your runbook calls for manual follow-up. Connector runbooks: [docs/runbooks/](../runbooks/). +2. **PortCo identity (SCIM & OIDC JIT)** — when your role includes org admin controls, configure **SCIM 2.0** bearer tokens and **group→role mappings**, or **OIDC JIT claim rules** for multi-entity portfolios. Rotate tokens when counsel or IdP policy requires it. Engineering detail: [OIDC_JIT_PROVISIONING.md](./OIDC_JIT_PROVISIONING.md), [hris-portco-integration-playbook.md](./roadmap/hris-portco-integration-playbook.md). +3. **HRIS platform & roster drift** — copy the **inbound URL** and **bearer secret** for iPaaS connectors; pick connector presets (Workday, ADP, BambooHR) when shown. Review **Roster drift** rows after nightly reconciliation; use **Reconcile now** when your runbook calls for manual follow-up. Connector runbooks: [docs/runbooks/](./runbooks/). 4. **Download NDJSON (500 newest)** gathers a downloadable slice once data returns (shows **Preparing export…** while running). 5. **Connector field mapping (operator notes)** stores JSON mapping drafts per connector; pick **Connector** from the drop-down list, edit the textarea JSON, tap **Save mapping** (**Saving…** while storing). 6. **Operational webhooks (org admin)** appears when permitted—under **Subscribe to** tick the operational event codes your stack needs, submit **Add webhook** (**Creating…** while busy), then manage listed endpoints with **Disable**, **Enable**, or **Delete**. @@ -1122,7 +1122,7 @@ Command center may spotlight **Integration backlog (*N* failed)** with shortcuts ### Context Sync (org administrators) -Separate from **Organization context (ISO 4)** above. When your role includes org admin controls, the **Context Sync (org admin)** panel on this page enables **governed REST read access** for IDE and agent tooling (`/api/contextsync/*`)—tenant opt-in, rate limits, and audit expectations apply. This is **not** a customer MCP server and **not** ISO scope editing. Engineering details: [procurement-integrations-appendix.md](../procurement-integrations-appendix.md). +Separate from **Organization context (ISO 4)** above. When your role includes org admin controls, the **Context Sync (org admin)** panel on this page enables **governed REST read access** for IDE and agent tooling (`/api/contextsync/*`)—tenant opt-in, rate limits, and audit expectations apply. This is **not** a customer MCP server and **not** ISO scope editing. Engineering details: [procurement-integrations-appendix.md](./procurement-integrations-appendix.md). ### What if things go wrong?