Stian/Shade
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
de25b1903328c9aecc6c157e0fb82518a2a0d2ef
Shade/docs/archive/V3.4.md
Sterister e6fdf31b49
Some checks failed
Test / test (push) Has been cancelled
Details
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Details
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
Details
Docker build and publish / docker (push) Has been cancelled
Details
Publish / publish (push) Has been cancelled
Details
release(v4.0.0): Shade GA — V3.x consolidation + audit prep 
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>
2026-05-03 18:35:35 +02:00

3.3 KiB
Raw Blame History

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

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

  • Default deploy uten OTel: ingen performance-regresjon (withTracer returnerer delt NOOP_HOOK når SHADE_OTEL_ENABLED ikke er satt).
  • 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).
  • 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.

Reference in New Issue View Git Blame Copy Permalink