54 lines
3.5 KiB
Markdown
54 lines
3.5 KiB
Markdown
# SafetyNet development instructions
|
|
|
|
## Use observability throughout development
|
|
|
|
The user explicitly requires OpenTelemetry diagnostics to be used for ongoing
|
|
debugging, optimization and feature work, not merely implemented and left idle.
|
|
|
|
- Start the protected local development collector with `npm run debug:collector`.
|
|
Check `http://127.0.0.1:4318/health` before relying on it. An existing live listener
|
|
must be inspected rather than blindly restarted.
|
|
- The backend uses `OTEL_EXPORTER_OTLP_ENDPOINT`; browser diagnostics require the
|
|
centrally signed `policy.diagnostics` configuration. Both remain centrally
|
|
disableable. Never bypass mandatory publication review to enable debugging.
|
|
- Exercise the relevant feature and inspect `/api/summary` and
|
|
`/api/trace/<traceId>`. Confirm actual exports, timings and parent/child correlation.
|
|
Successful startup alone is not proof of observability.
|
|
- On failures or slow paths, inspect the affected trace and add missing named
|
|
stages. Use `traceOperation` for backend code and the browser diagnostics helper
|
|
for privileged browser code. Record the relevant proof/trace IDs in local test
|
|
evidence without copying credentials or confidential content into ordinary logs.
|
|
- Use the durable event's `traceId` to retrieve the actual exported trace. Native
|
|
upload failures must include a recording `browser.upload.fault` span and a fixed
|
|
`safetynet.reason`; inherited ended spans can otherwise suppress diagnostic logs.
|
|
Do not put arbitrary rule text, exception messages, paths or credentials in reasons.
|
|
- Check collector `storedBytes` and exporter failures before long debug sessions.
|
|
The local protected receiver has a finite storage budget; missing exports or
|
|
rejected writes must not be mistaken for a successful observability proof.
|
|
- Check diagnostics `lifetimeFailedExports` as well as the current generation's
|
|
`failedExports`; disable/reconfiguration must not erase evidence of earlier
|
|
failures within the same browser process. Pre-enrollment startup has no signed
|
|
export authorization: use bounded local startup snapshots, and do not infer a
|
|
timeout's cause from later successful traces.
|
|
- Do not hide failed tests, weaken enforcement, or repeat a protected operation
|
|
because telemetry failed. Diagnostic traces are distinct from durable security
|
|
audit and encrypted forensic evidence.
|
|
- Local collector data is under ignored `data/observability`, encrypted with an
|
|
AES key protected by Windows DPAPI. This developer receiver is not a production
|
|
SIEM, durable forensic archive or remote authenticated collector.
|
|
- The collector pins its first previous encrypted archive and rotates later
|
|
generated segments. `/api/trace` indexes this process's recent spans only.
|
|
Older proof readers must inspect the guarded encrypted legacy/rolling segments
|
|
with the existing DPAPI key; never dump decrypted batches or key material.
|
|
|
|
## Repository and infrastructure
|
|
|
|
- Do not add CI/CD workflows, GitHub/Gitea Actions or forge configuration; the user
|
|
explicitly requested ordinary commits/pushes only.
|
|
- Keep credentials, `.env`, local databases, models, runtimes, builds and test
|
|
artifacts out of Git. Selected synthetic screenshots belong in `docs/media`.
|
|
- Infrastructure credentials are authoritative in Infisical. Read
|
|
`C:/Users/karl/Workspaces/InfrastructureOps/AGENTS.md` and `START-HERE.md` and use
|
|
protected selected-secret helpers; never print values or use legacy `local.env`.
|
|
- Windows file links use the actual absolute `C:/...` path, never `/C:/...`.
|