From c747921240b00f73d019b2e6783927d58c4a1435 Mon Sep 17 00:00:00 2001 From: DanFashauer Date: Wed, 13 May 2026 20:10:02 -0400 Subject: [PATCH] ci: add demo validation workflow --- .github/workflows/demo-validation.yml | 95 +++++++++++++++++++++++ README.md | 10 ++- docs/ARCHITECTURE_FUTURE_NOTES.md | 58 +++++++++++++- docs/CLAIM_BOUNDARIES.md | 69 +++++++++++++++- docs/DEMO_READINESS_CHECKLIST.md | 24 +++--- docs/INTEGRATION_PRIORITIES.md | 52 ++++++++++++- docs/PRODUCT_BOARD.md | 48 +++++++++++- docs/READINESS_HYGIENE_STATUS.md | 86 ++++++++++++++++++++ docs/REPO_ENV_AUDIT_2026-03-31.md | 4 + docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md | 4 + docs/ROADMAP.md | 43 +++++++++- docs/VALUE_MAP.md | 58 +++++++++++++- 12 files changed, 527 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/demo-validation.yml create mode 100644 docs/READINESS_HYGIENE_STATUS.md diff --git a/.github/workflows/demo-validation.yml b/.github/workflows/demo-validation.yml new file mode 100644 index 0000000..640906c --- /dev/null +++ b/.github/workflows/demo-validation.yml @@ -0,0 +1,95 @@ +name: Demo Validation + +on: + pull_request: + paths: + - 'src/app/demo/**' + - 'src/app/api/demo/**' + - 'src/lib/demo/**' + - 'scripts/capture-demo-media.ts' + - 'tests/api/demo-session-start.test.ts' + - 'docs/DEMO_MEDIA_CAPTURE.md' + - 'docs/DEMO_READINESS_CHECKLIST.md' + - 'package.json' + - 'package-lock.json' + - '.github/workflows/demo-validation.yml' + push: + branches: [main] + paths: + - 'src/app/demo/**' + - 'src/app/api/demo/**' + - 'src/lib/demo/**' + - 'scripts/capture-demo-media.ts' + - 'tests/api/demo-session-start.test.ts' + - 'docs/DEMO_MEDIA_CAPTURE.md' + - 'docs/DEMO_READINESS_CHECKLIST.md' + - 'package.json' + - 'package-lock.json' + - '.github/workflows/demo-validation.yml' + +permissions: + contents: read + +concurrency: + group: demo-validation-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate-demo: + name: Validate browser demo and media capture + runs-on: ubuntu-latest + timeout-minutes: 25 + + env: + CI: 'true' + NEXT_TELEMETRY_DISABLED: '1' + # Keep capture deterministic and local-only. The media script starts a local dev server if needed. + DEMO_MEDIA_SERVER_COMMAND: npm run dev + DEMO_MEDIA_SERVER_TIMEOUT_MS: '90000' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: npm + + - name: Setup Bun for demo media script + uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install dependencies + run: npm ci + + - name: TypeScript type check + run: npm run typecheck + + - name: ESLint + run: npm run lint + + - name: Build + run: npm run build + + - name: Run demo API unit test + run: npx vitest run tests/api/demo-session-start.test.ts + + - name: Generate deterministic demo media + run: npm run demo:media + env: + DEMO_MEDIA_BASE_URL: http://localhost:3000 + + - name: Verify demo media report exists + run: test -f artifacts/demo-media/capture-report.json + + - name: Upload demo media artifacts + if: always() + uses: actions/upload-artifact@v4 + with: + name: demo-media-${{ github.run_id }} + path: artifacts/demo-media/ + if-no-files-found: error + retention-days: 14 diff --git a/README.md b/README.md index 3d642f4..ba8daf1 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,14 @@ Identity + Badge + Device/Posture + Location Context See [docs/ARCHITECTURE_OVERVIEW.md](docs/ARCHITECTURE_OVERVIEW.md) for the evolving architecture model. +## Business-facing docs + +- [Claim boundaries](docs/CLAIM_BOUNDARIES.md) — safe language for MVP, demo, pilot, and production claims. +- [Value map](docs/VALUE_MAP.md) — executive, IT/security, workflow, audit, and pilot-metric mapping. +- [Product board](docs/PRODUCT_BOARD.md) — current MVP, demo confidence, pilot readiness, future roadmap, and non-goals. +- [Integration priorities](docs/INTEGRATION_PRIORITIES.md) — current demo integrations, first real targets, later targets, and safety boundaries. +- [Architecture future notes](docs/ARCHITECTURE_FUTURE_NOTES.md) — future gateway, remediation, AI-assist, guardrails, and non-goals. + ## Current repository status - **Demo-ready**: Yes — includes demo control scripts, demo validation flow, and demo-oriented tests. @@ -155,7 +163,7 @@ Demo and development paths are intentionally optimized for speed and validation. ## Roadmap preview -Near-term priorities include authentication hardening, trust consistency, source-of-truth cleanup, admin decomposition, and pilot readiness milestones. See [docs/ROADMAP.md](docs/ROADMAP.md). +Near-term priorities include readiness hygiene, removal of remaining unsafe defaults, package/toolchain normalization, demo verification, and pilot readiness milestones. See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/READINESS_HYGIENE_STATUS.md](docs/READINESS_HYGIENE_STATUS.md). ## Contributing diff --git a/docs/ARCHITECTURE_FUTURE_NOTES.md b/docs/ARCHITECTURE_FUTURE_NOTES.md index 4aa7881..3173c0a 100644 --- a/docs/ARCHITECTURE_FUTURE_NOTES.md +++ b/docs/ARCHITECTURE_FUTURE_NOTES.md @@ -1,3 +1,57 @@ -# Architecture Future Notes +# SignalGrid Architecture Future Notes -(Your content here) \ No newline at end of file +These notes describe future architecture direction. They are not current production claims. + +## Event-driven decision gateway direction + +SignalGrid should evolve toward an event-driven decision gateway that: + +- Receives signed events from badge, identity, posture, location, and session sources. +- Normalizes context into a consistent policy input. +- Produces explicit decisions such as allow, deny, step-up, quarantine request, or ticket request. +- Emits auditable decision records and downstream integration events. +- Keeps customer-specific integrations behind well-defined adapters. + +The gateway should remain deterministic and explainable for high-consequence frontline workflows. + +## Constrained remediation playbooks + +Future remediation should be modeled as bounded playbooks, not open-ended automation. A safe playbook should include: + +- Trigger conditions and required input fields. +- Allowed actions and disallowed actions. +- Approval requirements for high-risk steps. +- Timeout, retry, and rollback behavior. +- Re-check criteria before access is allowed. +- Audit records for `attempted`, `succeeded`, `failed`, and `final decision` states. + +## AI-assisted explanation/classification + +AI-assisted capabilities may be useful later for summarizing decision context, classifying event patterns, or drafting operator-facing explanations. These should remain future-only until guardrails are implemented. + +Any AI-assisted workflow must: + +- Avoid autonomous high-risk enforcement. +- Use structured inputs and bounded outputs. +- Preserve policy-engine authority for final decisions. +- Cite the signals and rules behind generated explanations. +- Fail closed or require review when confidence is low or inputs are incomplete. +- Avoid exposing secrets, credentials, or unnecessary personal data. + +## Guardrails + +Future architecture work should preserve these guardrails: + +- Signed inputs for security-sensitive events. +- Explicit environment configuration with no shared-stage or production default secrets. +- Least-privilege integration credentials. +- Clear separation between demo simulation and production code paths. +- Auditable policy decisions and integration actions. +- Deterministic fallback behavior for missing, stale, or conflicting signals. + +## Non-goals + +- Replacing customer IAM, UEM/MDM, DEX, NAC, SIEM, SOAR, or ITSM platforms. +- Building a generic autonomous agent that can take unrestricted external actions. +- Treating AI-generated explanations as policy decisions. +- Making production-readiness claims before deployment validation, load testing, and customer-specific integration review are complete. diff --git a/docs/CLAIM_BOUNDARIES.md b/docs/CLAIM_BOUNDARIES.md index 33f0838..b04d314 100644 --- a/docs/CLAIM_BOUNDARIES.md +++ b/docs/CLAIM_BOUNDARIES.md @@ -1,3 +1,68 @@ -# Claim Boundaries +# SignalGrid Claim Boundaries -(Your content here) \ No newline at end of file +SignalGrid should be described with clear MVP/demo boundaries. Use this document when preparing website copy, demos, sales materials, investor notes, or partner outreach. + +## What SignalGrid can claim today + +SignalGrid can credibly claim that it: + +- Provides a working MVP/demo path for posture-aware shared-device session decisions. +- Evaluates identity, device posture, session context, and policy inputs before returning an access outcome. +- Demonstrates deterministic outcomes for compliant, non-compliant, and unknown-posture scenarios. +- Fails closed for unknown posture in the current session-start path unless an explicit local/demo override is configured. +- Produces auditable decision context and demo-visible integration/action records. +- Includes simulated/demo workflows for NAC, SIEM, ITSM, and remediation-oriented narratives. +- Includes production-oriented packaging and runbook foundations that still require deployment-specific validation. + +## What is simulated or demo-only + +The following should be labeled as simulated, deterministic demo behavior, or implementation foundation unless validated in a real pilot environment: + +- Browser `/demo` scenarios and demo media outputs. +- Demo integration payload previews for NAC, SIEM, ITSM, and related action logs. +- Remediation attempts described in the current demo narrative. +- Any fallback storyboard media generated when browser capture is unavailable. +- Local/demo default keys or local-only script configuration. +- Buyer-safe sample data, seeded posture fixtures, and simulated frontline scenarios. + +## What not to claim yet + +Do not claim the following until pilot or production validation exists for the target environment: + +- Production readiness for a customer deployment. +- Guaranteed uptime, latency, scale, resilience, or compliance outcomes. +- Certified regulatory compliance such as HIPAA, SOC 2, ISO 27001, FedRAMP, or PCI. +- Fully automated remediation with verified post-remediation re-checks. +- Live customer integrations with a specific IAM, UEM/MDM, DEX, NAC, SIEM, ITSM, or badge system unless that integration has been configured and validated. +- Replacement of existing identity, endpoint, observability, network, ticketing, or device-management systems. +- AI-driven autonomous enforcement decisions. + +## Replacement boundaries + +SignalGrid is positioned as a decision and orchestration layer between authentication, device posture, and enforcement systems. It does **not** replace: + +| Existing category | Boundary language | +| --- | --- | +| IAM / identity provider | SignalGrid uses identity context; it does not replace identity proofing, authentication, or directory ownership. | +| UEM / MDM | SignalGrid consumes posture and enrollment signals; it does not manage full device lifecycle, configuration, or app deployment. | +| DEX / observability | SignalGrid can use operational signals; it does not replace broad employee-experience monitoring or telemetry platforms. | +| NAC / network enforcement | SignalGrid can request enforcement actions; it does not replace network control planes. | +| SIEM / SOAR | SignalGrid emits and enriches events; it does not replace security analytics, incident investigation, or enterprise SOAR governance. | +| ITSM | SignalGrid can create or update workflow records; it does not replace ticketing, change management, or service operations ownership. | + +## Safe phrasing + +Use language like: + +- “SignalGrid sits between authentication and enforcement to make shared-device access decisions based on runtime trust.” +- “The current MVP demonstrates deterministic access outcomes and auditable decision context.” +- “Pilot readiness depends on customer-specific integration validation, operational runbooks, and removal of local/demo defaults.” +- “Remediation is currently shown as a constrained demo narrative unless explicitly implemented and validated in the target environment.” + +Avoid language like: + +- “Production-ready today.” +- “Replaces your MDM/IAM/NAC/SIEM/ITSM stack.” +- “Fully autonomous remediation.” +- “Compliance guaranteed.” +- “AI decides who gets access.” diff --git a/docs/DEMO_READINESS_CHECKLIST.md b/docs/DEMO_READINESS_CHECKLIST.md index 1a9f763..c4ddf49 100644 --- a/docs/DEMO_READINESS_CHECKLIST.md +++ b/docs/DEMO_READINESS_CHECKLIST.md @@ -89,7 +89,7 @@ The safe demo API mirrors the real session-start response envelope closely enoug - Security event stream may include allow event depending on policy/event pipeline. ### Current readiness status -- **Partially blocked** in this repo state because session-start posture adapters currently return `unknown` by default, which causes fail-closed deny unless `UNKNOWN_POSTURE_MODE=allow`. +- **Ready when seeded with fresh posture data** because session-start posture adapters now read the shared telemetry posture store. Missing or expired posture still correctly fails closed unless `UNKNOWN_POSTURE_MODE=allow`. --- @@ -159,8 +159,8 @@ The safe demo API mirrors the real session-start response envelope closely enoug - Deterministic executive demo script orchestration for healthcare deny scenario. ### Mocked / simulated now -- `getFleetContext` and `getUEMContext` in session-start path are hardcoded to `unknown` (not live adapter-backed). -- `demo:seed` and `sim:posture` are largely simulation/logging utilities and do not provide authoritative live adapter state for session-start. +- Browser `/demo` scenarios are deterministic and simulated for buyer-safe walkthroughs. +- Demo/default keys used by local scripts are not production controls. - Remediation attempt in scenario B is talk-track/simulated, not a stateful remediation-retry decision loop. ### Future work (demo-readiness relevant only) @@ -172,10 +172,10 @@ The safe demo API mirrors the real session-start response envelope closely enoug ## 4) Remaining Technical Blockers (Can Break Demo) -1. **Posture adapter disconnect (highest risk):** session-start posture service is hardcoded unknown; this can collapse intended compliant/non-compliant differentiation. -2. **Remediation path gap:** required MVP scenario mentions remediation attempt, but session-start currently jumps directly to deny on non-compliance. -3. **Test drift in session-start API expectations:** current API tests show status-code expectation mismatches, indicating contract drift risk before buyer demos. -4. **Demo verification coupling:** `/api/demo/verify` PASS is tied to denied timeline + specific action event presence; allow-path demo validation is under-specified. +1. **Remediation path gap:** required MVP scenario mentions remediation attempt, but session-start currently jumps directly to deny on non-compliance. +2. **Scenario verification coupling:** `/api/demo/verify` PASS is tied to denied timeline + specific action event presence; allow-path and unknown-path demo validation are under-specified. +3. **Local default-key confusion:** demo/test scripts still use local defaults; hosts must avoid presenting those as shared-stage or production-safe settings. +4. **Environment drift risk:** package-manager and toolchain choices are not yet fully normalized across README, scripts, and automation. --- @@ -192,9 +192,9 @@ The safe demo API mirrors the real session-start response envelope closely enoug ## 6) Demo-Readiness Next Fix Tasks (No Feature Expansion) -1. **Wire real posture reads in session-start service** from existing telemetry/UEM stores so scenario A and B are both first-class and deterministic. -2. **Implement minimal remediation attempt state machine** in session-start flow (single retry path + explicit audit fields). -3. **Add one golden script for each scenario** (allow/deny/unknown) that returns machine-checkable pass/fail JSON. -4. **Align session-start API tests with contract** (or contract with tests) to remove status-code ambiguity before external demos. -5. **Extend `/api/demo/verify` with scenario selector** so each of the three required scenarios can be verified explicitly. +1. **Implement minimal remediation attempt state machine** in session-start flow (single retry path + explicit audit fields), or keep remediation consistently labeled as simulated. +2. **Add one golden script for each scenario** (allow/deny/unknown) that returns machine-checkable pass/fail JSON. +3. **Extend `/api/demo/verify` with scenario selector** so each of the three required scenarios can be verified explicitly. +4. **Document local-only demo defaults** so default keys are never mistaken for shared-stage or production configuration. +5. **Keep seeded posture fixtures fresh** in demo scripts so scenario A and B remain deterministic. diff --git a/docs/INTEGRATION_PRIORITIES.md b/docs/INTEGRATION_PRIORITIES.md index d9f99ca..b85a087 100644 --- a/docs/INTEGRATION_PRIORITIES.md +++ b/docs/INTEGRATION_PRIORITIES.md @@ -1,3 +1,51 @@ -# Integration Priorities +# SignalGrid Integration Priorities -(Your content here) \ No newline at end of file +SignalGrid integrates by consuming identity/posture/context signals, making a decision, and coordinating downstream actions. Current integration language should distinguish demo simulation from validated customer integrations. + +## Current simulated/demo integrations + +The current repository can demonstrate integration behavior through deterministic demo flows and local payload previews for: + +- Badge/session-start events. +- Device posture fixtures and telemetry-store reads. +- NAC-style quarantine/action records. +- SIEM-style security event records. +- ITSM-style ticket/action records. +- Demo media and storyboard outputs. + +These are useful for explaining the control loop, but they should not be described as live production integrations unless connected and validated in a target environment. + +## First real integration targets + +Prioritize the smallest integration set needed to prove a pilot workflow: + +1. **Identity / badge source** — confirm who is requesting access and map badge/session context to a user. +2. **UEM/MDM or endpoint posture source** — provide fresh compliant, non-compliant, or unknown posture signals. +3. **Audit/event sink** — preserve decision evidence in a customer-approved log destination. +4. **ITSM workflow** — create reviewable tickets or tasks for denied or remediated sessions. +5. **NAC or enforcement target** — only after policy, rollback, and safety boundaries are explicit. + +## Later integration targets + +After the first pilot workflow is stable, consider: + +- Additional MDM/UEM providers. +- Endpoint security and DEX telemetry providers. +- SIEM/SOAR enrichment and correlation workflows. +- HRIS or workforce context sources where appropriate and approved. +- Location/RTLS systems for shared-device return or zone context. +- Multiple enforcement systems for complex frontline environments. + +## Integration safety boundaries + +- Do not use production credentials in demos. +- Do not call real webhooks from browser demo or media capture flows. +- Require explicit signing secrets and scoped credentials for shared/staging environments. +- Prefer read-only or audit-only pilot modes before write/enforcement actions. +- Use least-privilege service accounts and short rollback paths. +- Keep high-risk actions disabled until policy ownership and approval gates are clear. +- Record integration actions with enough detail for post-demo or post-pilot review. + +## Pilot sequencing recommendation + +Start with identity, posture, and audit evidence. Add ticketing next. Add enforcement only when customer stakeholders agree on policy, blast radius, rollback, and success metrics. diff --git a/docs/PRODUCT_BOARD.md b/docs/PRODUCT_BOARD.md index 740d5f8..c0552f0 100644 --- a/docs/PRODUCT_BOARD.md +++ b/docs/PRODUCT_BOARD.md @@ -1,3 +1,47 @@ -# Product Board +# SignalGrid Product Board -(Your content here) \ No newline at end of file +This board summarizes current MVP scope, near-term readiness work, pilot-readiness work, and future direction. It is intentionally conservative so the repository remains business-presentable without overstating maturity. + +## Current MVP + +- Browser `/demo` experience for deterministic buyer-safe walkthroughs. +- Safe simulated demo API for compliant, non-compliant, and unknown-posture outcomes. +- Session-start groundwork for signed requests, badge mapping, posture checks, and allow/deny responses. +- Unknown-posture fail-closed behavior by default. +- Demo tooling for scripted walkthroughs, validation, and media capture. +- Production-oriented runbook/container/API foundation that still needs environment-specific validation. +- Security, disclaimer, and claim-boundary documentation for MVP positioning. + +## Near-term demo confidence work + +- Keep demo scenarios deterministic and easy to reset. +- Add scenario-specific verification for allow, deny, and unknown-posture paths. +- Keep generated demo media current after demo UI/API changes. +- Maintain clear labels for simulated behavior and sample data. +- Avoid real webhooks, production secrets, or production data in demo workflows. + +## Pilot-readiness work + +- Remove or explicitly local-gate remaining default keys/secrets in runtime routes. +- Validate Docker build/run/healthcheck in a Docker-capable environment. +- Define target customer workflow, success metrics, owners, rollback path, and support model. +- Validate customer-selected integrations with scoped credentials and safe test targets. +- Confirm audit records are complete enough for pilot review. +- Document operational procedures for deployment, monitoring, incidents, and rollback. + +## Future roadmap + +- Event-driven decision gateway for runtime access decisions. +- Constrained remediation playbooks with explicit audit states. +- Deeper posture integrations with selected UEM/MDM and endpoint telemetry systems. +- More complete admin workflows for policy configuration, review, and reporting. +- Expanded integration catalog after first pilot workflows prove repeatable. +- Optional AI-assisted explanation/classification features under strict guardrails. + +## Non-goals + +- Replacing IAM, UEM/MDM, DEX, NAC, SIEM, SOAR, or ITSM platforms. +- Broad autonomous remediation without explicit policy, approval, isolation, and audit controls. +- Expanding product surface before demo and pilot evidence is stable. +- Claiming production readiness before deployment validation is complete. +- Using real customer data in demos or media capture workflows. diff --git a/docs/READINESS_HYGIENE_STATUS.md b/docs/READINESS_HYGIENE_STATUS.md new file mode 100644 index 0000000..e903641 --- /dev/null +++ b/docs/READINESS_HYGIENE_STATUS.md @@ -0,0 +1,86 @@ +# SignalGrid Readiness Hygiene Status + +Date: 2026-05-13 +Scope: repository documentation and readiness-facing checks for demo, pilot, launch, and production hygiene. + +## Executive summary + +SignalGrid is **demo-ready for controlled conversations** and has several hardening improvements already reflected in code, but it is **not yet pilot-ready or production-ready**. The remaining readiness gap is mostly around production-safe defaults, canonical package-manager/toolchain hygiene, Docker/environment validation, and cleanup of stale documentation that described older runtime behavior. + +Use this file as the current source of truth for readiness hygiene until the open items below are closed or moved into tickets. + +## Current readiness state + +| Area | Current state | Notes | +| --- | --- | --- | +| Browser demo | Ready | `/demo` uses deterministic simulated scenarios and is safe for walkthroughs. | +| Scripted executive demo | Ready with constraints | Canonical deny-path demo is still the safest live script. | +| Compliant allow scenario | Ready when posture fixture is seeded | Session-start now reads posture from the telemetry store; no unknown-posture bypass should be required when a fresh compliant fixture exists. | +| Unknown posture behavior | Complete | Unknown posture fails closed by default unless `UNKNOWN_POSTURE_MODE=allow` is explicitly set. | +| Session extension wording | Complete | Existing active sessions update `expiresAt` and `lastActivityAt` before returning `Existing session extended`. | +| API-key helper hardening | Complete for `src/lib/utils/apiKeyAuth.ts` | This helper now fails closed when `ADMIN_API_KEY` is absent. | +| Webhook dispatcher signing fallback | Complete for integration dispatcher | Webhook dispatch now fails if a signing secret cannot be resolved. | +| ITSM credential encryption fallback | Complete for ITSM store | Credential encryption now requires `ITSM_ENCRYPTION_KEY` or `ENCRYPTION_KEY`. | +| Public `/api/v1/*` compatibility defaults | Open | `src/app/api/v1/[...path]/route.ts` still has fallback `test-api-key` and `dev-secret` values. | +| Package-manager/toolchain policy | Open | README uses npm, many scripts/docs use Bun, and both lockfiles are present. | +| Docker/customer-hosted validation | Open | Production runbook exists, but Docker build/run validation still needs a Docker-capable environment. | +| Business/manual cutover | Open / external | Domain, email, legal, bank, outreach, and PR cleanup tasks are founder/manual activities. | + +## Completed readiness hygiene + +1. **Unknown posture fail-closed default is implemented.** Session start rejects unknown posture with `DEVICE_POSTURE_UNKNOWN` unless `UNKNOWN_POSTURE_MODE=allow` is deliberately enabled. +2. **Session-start posture reads are no longer hardcoded unknown.** Fleet and UEM context now read the shared telemetry posture store and only return unknown when data is missing or expired. +3. **Non-compliant deny path remains the canonical live demo.** The executive script path can seed non-compliant posture and demonstrate deny-side effects for security/integration visibility. +4. **API-key helper fallback was removed.** The reusable API-key helper requires an explicit `ADMIN_API_KEY` and returns `API_KEY_NOT_CONFIGURED` when absent. +5. **Webhook dispatcher fallback secret was removed.** The dispatcher records a failed delivery when no signing secret is configured rather than signing with a predictable default. +6. **ITSM credential encryption fallback was removed.** ITSM credential writes now require an explicit encryption key. +7. **Session extension semantics are aligned.** The active-session branch updates expiration/activity timestamps before reporting that the session was extended. + +## Not completed yet + +### P0 — Remaining security/config defaults + +- **Public v1 API auth fallback remains.** `src/app/api/v1/[...path]/route.ts` still falls back to `test-api-key` when `ADMIN_API_KEY` is absent. Remove this before shared staging, pilots, or production. +- **Public v1 signature fallback remains.** The same route still falls back to `dev-secret` when `DEVICE_WEBHOOK_SECRET` and `BACKEND_SIGNING_SECRET` are absent. Remove or explicitly gate this for local-only test mode. +- **Demo/test scripts still publish default keys.** Demo and test helpers intentionally seed local defaults such as `dev-admin-key-12345`; keep them isolated to local/demo workflows and do not treat them as production-safe defaults. + +### P1 — Environment and repo reproducibility + +- **Canonical package manager is unresolved.** README onboarding says npm, while active demo/test scripts and CI-style commands rely heavily on Bun. Pick one primary path, document the secondary path if needed, and keep lockfiles consistent. +- **Toolchain versions need pinning.** Add a Node/Bun version policy (`.nvmrc`, `.node-version`, `.tool-versions`, `.npmrc`, or equivalent) and avoid moving `latest` targets in automation. +- **Docker validation remains unproven in this environment.** Run production image build/run checks in a Docker-capable environment and record the exact commands/results in the production runbook or a validation report. + +### P1 — Demo/pilot maturity + +- **Real remediation loop is not yet implemented.** Current remediation language should remain framed as demo narrative/simulated side effects until there is an audited `attempted → re-check → final decision` workflow. +- **Scenario verification should be split by scenario.** `/api/demo/verify` is most useful for the deny-path timeline; add explicit allow/deny/unknown selectors before using it as broad demo proof. +- **Pilot success metrics and operational owner model need customer-specific completion.** The pilot execution docs provide templates, but signed scope, metrics, owner, rollback, and support paths are not yet completed. + +### P2 — Documentation/source-of-truth cleanup + +- **Placeholder docs remain.** `docs/CLAIM_BOUNDARIES.md`, `docs/VALUE_MAP.md`, `docs/PRODUCT_BOARD.md`, `docs/INTEGRATION_PRIORITIES.md`, and `docs/ARCHITECTURE_FUTURE_NOTES.md` still need real content or deletion if they are not intended sources of truth. +- **Old dated review docs should be treated as historical.** `docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md` and `docs/REPO_ENV_AUDIT_2026-03-31.md` contain useful backlog context, but several findings have changed and should not override this status file. +- **Manual cutover doc still references PR #72.** Confirm current GitHub state; if PR #72 is already closed or irrelevant, update or archive that checklist. + +## Outdated or conflicting docs to reconcile + +| Document | Conflict/outdated point | Current guidance | +| --- | --- | --- | +| `docs/DEMO_READINESS_CHECKLIST.md` | Older text said posture adapters were hardcoded unknown and compliant/non-compliant scenarios were blocked. | Updated to state posture reads come from the telemetry store and scenarios are ready when seeded with fresh fixtures. | +| `docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md` | Lists some findings as still open even though API-key helper, webhook dispatcher, ITSM encryption, unknown posture, and session extension have been hardened. | Treat as historical backlog evidence; use this status file for current state. | +| `docs/REPO_ENV_AUDIT_2026-03-31.md` | Refers to the dated hardening backlog as still prioritized wholesale. | Keep environment/package-manager findings active, but re-check individual code findings before implementation. | +| `docs/CODEX_COMPLETE_CUTOVER_CHECKLIST.md` | Mentions PR #72 and launch-critical PR noise without current GitHub verification. | Treat as manual GitHub cleanup pending confirmation. | +| `README.md` | Says pilot readiness is tracked in roadmap docs while roadmap was previously a placeholder. | Roadmap now summarizes active readiness priorities and links to this status file. | + +## Next decision checklist + +Before calling SignalGrid pilot-ready, all of the following should be true: + +- [ ] No runtime route used in shared environments has default API keys, default HMAC secrets, or default encryption keys. +- [ ] Demo/test defaults are explicitly local-only and impossible to enable accidentally in production/shared staging. +- [ ] Package manager, lockfile, and toolchain versions are documented and pinned. +- [ ] Docker production build/run/healthcheck path is validated in a Docker-capable environment. +- [ ] Demo verification has independent pass/fail checks for allow, deny, and unknown scenarios. +- [ ] Remediation claims are either implemented as an auditable loop or consistently described as simulated/demo narrative. +- [ ] Placeholder docs are filled, deleted, or marked intentionally deferred. +- [ ] Manual business/cutover items are completed or clearly excluded from technical readiness. diff --git a/docs/REPO_ENV_AUDIT_2026-03-31.md b/docs/REPO_ENV_AUDIT_2026-03-31.md index 0cb79a6..b7d25a4 100644 --- a/docs/REPO_ENV_AUDIT_2026-03-31.md +++ b/docs/REPO_ENV_AUDIT_2026-03-31.md @@ -1,5 +1,9 @@ # Repository + Environment Audit (2026-03-31) +## Historical status note + +This audit is retained as dated environment evidence. Use `docs/READINESS_HYGIENE_STATUS.md` and `docs/ROADMAP.md` for current readiness priorities and re-check code before acting on historical findings. + ## Scope This audit covers: - Local execution environment sanity. diff --git a/docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md b/docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md index 8227d93..4fb2a39 100644 --- a/docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md +++ b/docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md @@ -1,5 +1,9 @@ # Repo Review & Recommended Next Steps (2026-03-30) +## Historical status note + +This review is retained as dated backlog evidence. Several findings have since changed; use `docs/READINESS_HYGIENE_STATUS.md` for the current completed/open/conflicting readiness list before acting on any item below. + ## Scope of this review This is a focused, repo-wide hardening review intended to identify what should be fixed next after the recent admin-auth tightening work. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 834847b..5d4c2e5 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,3 +1,44 @@ # Roadmap -(Your content here) \ No newline at end of file +Date: 2026-05-13 +Current source of truth for readiness hygiene: [`docs/READINESS_HYGIENE_STATUS.md`](READINESS_HYGIENE_STATUS.md). + +## Current phase + +SignalGrid is in **controlled demo readiness**. The immediate goal is to move from repeatable demo proof to a constrained pilot posture without overstating production maturity. + +## Phase 0 — Readiness hygiene closeout + +- Remove remaining public v1 default API-key and HMAC-secret fallbacks. +- Isolate local/demo defaults behind explicit local-only scripts and documentation. +- Choose and document the canonical package manager and lockfile strategy. +- Pin local and CI toolchain versions. +- Fill, archive, or delete placeholder docs that are not active sources of truth. +- Reconcile dated audit/review documents with the current readiness status. + +## Phase 1 — Demo confidence + +- Keep `/demo` as the safe buyer walkthrough path with simulated deterministic scenarios. +- Keep the executive deny-path demo as the canonical live script until all scenario checks are equally strong. +- Add scenario-specific verification for allow, deny, and unknown-posture outcomes. +- Ensure any remediation language is explicitly labeled as simulated until a real audited loop exists. + +## Phase 2 — Pilot readiness + +- Validate production container build/run/healthcheck workflow in a Docker-capable environment. +- Define pilot customer scope, success metrics, owners, rollback steps, and support paths. +- Harden shared/staging environment configuration so missing secrets fail closed. +- Confirm operational runbook coverage for deployment, monitoring, incidents, and rollback. + +## Phase 3 — Production readiness + +- Replace temporary admin API-key operation with customer-approved identity/admin access. +- Complete integration-specific security validation for customer-selected NAC, SIEM, ITSM, MDM/UEM, and identity systems. +- Add load, resiliency, and security validation reports for the actual deployment topology. +- Finalize legal/commercial/security review artifacts before external production use. + +## Non-goals for current phase + +- Broad feature expansion beyond demo/pilot-critical trust decisions. +- Claims that SignalGrid replaces MDM, IAM, NAC, SIEM, or ITSM systems. +- Production availability, compliance, or remediation guarantees before validation evidence exists. diff --git a/docs/VALUE_MAP.md b/docs/VALUE_MAP.md index b952256..b6c129a 100644 --- a/docs/VALUE_MAP.md +++ b/docs/VALUE_MAP.md @@ -1,3 +1,57 @@ -# Value Map +# SignalGrid Value Map -(Your content here) \ No newline at end of file +SignalGrid connects shared-device access decisions to executive, IT/security, frontline, and audit outcomes. This map keeps the business value concise without expanding beyond current MVP/demo readiness. + +## Executive value + +| Outcome | SignalGrid contribution | +| --- | --- | +| Risk reduction | Makes access decisions explicit instead of assuming shared-device trust. | +| Operational resilience | Gives frontline workflows a deterministic allow/deny/step-up path when runtime conditions change. | +| Accountability | Preserves decision context for review, audit, and post-incident learning. | +| Tool leverage | Uses existing identity, posture, ticketing, security, and enforcement systems instead of replacing them. | +| Pilot clarity | Defines measurable workflow outcomes before broader rollout. | + +## IT and security value + +- Connects badge/session context with device posture and policy decisions. +- Fails closed when posture is unknown by default. +- Provides a single decision point that can coordinate downstream actions. +- Makes NAC, SIEM, ITSM, and audit outputs easier to explain in a shared-device workflow. +- Reduces ambiguity between “authenticated user” and “trusted session.” + +## Frontline/shared-device workflow value + +- Supports fast, deterministic session decisions for shared and mobile devices. +- Reduces manual interpretation of device health and access risk. +- Helps teams understand why access was allowed, denied, or routed to another action. +- Keeps demos focused on realistic healthcare, logistics, and regulated frontline scenarios. +- Protects user experience by making policy behavior predictable before pilot rollout. + +## Audit and compliance value + +SignalGrid is not a compliance certification product, but it can strengthen evidence quality by recording: + +- Identity and badge/session context used in the decision. +- Device posture status and unknown/non-compliant handling. +- Policy outcome, risk context, and final decision. +- Downstream demo or integration action records. +- Timestamps and reason codes useful for review. + +## Measurable pilot metrics + +Potential pilot success metrics should be agreed with the design partner before deployment. Examples include: + +| Metric | Why it matters | +| --- | --- | +| Unknown-posture deny rate | Shows where posture telemetry or enrollment is incomplete. | +| Non-compliant access attempts | Quantifies risky shared-device sessions before access proceeds. | +| Decision latency | Confirms the workflow remains usable for frontline staff. | +| Manual escalation volume | Measures whether decision context reduces help desk or security triage burden. | +| Successful compliant starts | Confirms trusted sessions proceed without unnecessary friction. | +| Audit record completeness | Verifies that reviewers can reconstruct access decisions. | +| Integration action accuracy | Confirms downstream NAC/SIEM/ITSM actions match policy intent during pilot scope. | + +## Pilot value statement + +A good pilot should prove that SignalGrid can make shared-device access decisions clearer, safer, and easier to audit without adding unacceptable frontline friction.