Sterister
e6fdf31b49
Some checks failed
Test / test (push) Has been cancelled
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
Docker build and publish / docker (push) Has been cancelled
Publish / publish (push) Has been cancelled
V3.1 → V3.12 consolidated and tagged for the first GA release. Wire format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers byte-for-byte. The version bump is semantic: audit-cycle complete, opt-in surface fully exposed, threat model refreshed for every new surface. Highlights: - All 24 @shade/* packages bumped to 4.0.0 in lockstep. - CHANGELOG 4.0.0 section is the canonical manifest of what landed. - THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12 Web-Worker boundary) + residual-risks table refreshed. - OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox, bridge, observer, /metrics, /healthz, /ready. - MIGRATION 0.3.x → 4.0 documented + smoke-tested against shade migrate-storage on a real SQLite DB. - docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer. - scripts/soak.ts harness for the GA-stable 2-week soak window. - All V*.md plans archived under docs/archive/ with Status: Done. - Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen non-realtime stack. Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green. Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports version 4.0.0 on /health. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# Shade V3.4 — Observability v2 (OpenTelemetry)
|
||
|
||
**Status:** Implementert (2026-05-02) — `@shade/observability` 0.1.0,
|
||
hekt inn i sdk/transfer/server/files/core. Off by default; flip
|
||
`SHADE_OTEL_ENABLED=1` for å aktivere.
|
||
**Effort:** M (2–4 uker)
|
||
**Forrige:** V3.1
|
||
**Adresserer:** V2.3 §4
|
||
|
||
---
|
||
|
||
## Mål
|
||
|
||
Gi produksjonsteam **distribuerte spor** rundt `TransferEngine`,
|
||
prekey-routes og `@shade/files` — uten å lekke plaintext-adresser, payloads
|
||
eller eksakte chunk-størrelser. Bygger videre på Prometheus-metrics som
|
||
allerede finnes.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### Inn
|
||
|
||
- Opt-in OpenTelemetry-instrumentasjon via `@opentelemetry/api`.
|
||
- Spans rundt:
|
||
- `TransferEngine.upload` / `.download` (med lane-tags, retry-counts).
|
||
- `ShadeSessionManager.encrypt` / `.decrypt` (per-peer mutex-akkvisisjon,
|
||
ratchet-step).
|
||
- `createPrekeyRoutes` (per route, status-koder).
|
||
- `@shade/files` op-handlers (har allerede `onMetric` — utvides til OTel).
|
||
- PII-policy-doc: hva som **aldri** logges, hva binnes, hva pseudonymiseres.
|
||
- Sample-policy default off; on med `SHADE_OTEL_ENABLED=1`.
|
||
|
||
### Ut
|
||
|
||
- Trace-eksport til SaaS-leverandører (det er deploy-konfig, ikke vår kode).
|
||
- Logg-aggregering — `@shade/server` har allerede strukturert JSON.
|
||
|
||
---
|
||
|
||
## Design
|
||
|
||
### Span-attributter
|
||
|
||
| Attribute | Verdi |
|
||
|-----------|-------|
|
||
| `shade.peer.hash` | `sha256(address).slice(0, 8)` — stabil pseudonym |
|
||
| `shade.bytes.bin` | binnet — `"≤4KB"`, `"4–64KB"`, `"64KB–1MB"`, `"≥1MB"` |
|
||
| `shade.lane.count` | 1 / 4 / 16 |
|
||
| `shade.retry.count` | int |
|
||
| `shade.error.code` | `SHADE_*`-kode |
|
||
|
||
**Aldri:** `shade.peer.address`, `shade.payload`, `shade.bytes.exact`.
|
||
|
||
### API
|
||
|
||
```ts
|
||
import { withTracer } from '@shade/observability';
|
||
|
||
const shade = await createShade({
|
||
...,
|
||
observability: withTracer(myTracer, { sample: 0.1 }),
|
||
});
|
||
```
|
||
|
||
`withTracer()` er no-op hvis `tracer` er `undefined` eller
|
||
`SHADE_OTEL_ENABLED` ikke er satt.
|
||
|
||
---
|
||
|
||
## Leveranser
|
||
|
||
### Pakker
|
||
|
||
- Ny submodul `@shade/observability` (peer-dep `@opentelemetry/api`).
|
||
- Hooks i `@shade/sdk`, `@shade/transfer`, `@shade/server`, `@shade/files`.
|
||
|
||
### Tester
|
||
|
||
- Span emitteres med riktige attributter (mock tracer).
|
||
- Sample-rate respekteres.
|
||
- Off-by-default verifisert.
|
||
- Regex-grep mot recorder fanger plaintext-PII.
|
||
|
||
### Dokumentasjon
|
||
|
||
- `docs/observability.md` — setup + PII-policy.
|
||
- `docs/DEPLOYMENT.md` — environment-variabler.
|
||
|
||
---
|
||
|
||
## Akseptansekriterier
|
||
|
||
- [x] Default deploy uten OTel: ingen performance-regresjon (`withTracer`
|
||
returnerer delt `NOOP_HOOK` når `SHADE_OTEL_ENABLED` ikke er satt).
|
||
- [x] Med OTel på: spans for upload/download (`shade.transfer.upload`,
|
||
`shade.transfer.download`), prekey-routes (`shade.prekey.request`),
|
||
session encrypt/decrypt (`shade.session.{encrypt,decrypt}`), og
|
||
`@shade/files` ops (`shade.files.op`).
|
||
- [x] Automatisert grep-test fanger plaintext-PII i spans
|
||
(`packages/shade-observability/tests/integration-pii.test.ts` +
|
||
`packages/shade-transfer/tests/observability.test.ts`,
|
||
`safeAttribute()` blokkerer fra-utvikler-introduksert PII).
|
||
|
||
---
|
||
|
||
## Avhengigheter
|
||
|
||
- V3.1 — basis-docs.
|
||
|
||
---
|
||
|
||
## Risiko
|
||
|
||
- **Performance-overhead.** Mitiger ved aggressiv default-off + sampling.
|
||
- **PII-lekkasje** hvis utviklere legger til egne attributter. Mitiger ved
|
||
å publisere "safe attribute"-helpers og PII-linter.
|
||
|
||
---
|
||
|
||
## Migrasjon
|
||
|
||
Ingen — opt-in.
|