Skip to content

Integrator-guidance additions from pre-outreach dry-run review #216

Description

@the-sarge

Low/nit documentation additions surfaced by the internal pre-outreach dry-run review of issues #29/#30 (fresh-context AI pass; recorded as hygiene, not external review). None block outreach; fold into the eventual review-driven doc work.

  • Online-guessing caller responsibility: draft-21 allows one password guess per active interaction; no doc tells applications to count/throttle ErrConfirmationFailed per identity/source. Add a short section to docs/integration-guidance.md and list residual online guessing in docs/threat-model.md.
  • Cleartext-visibility asymmetry: SessionID and LocalAssociatedData travel in cleartext wire fields; Context and Password never leave the process. No doc states this; an integrator could place semi-sensitive identifiers in AD. One paragraph in docs/integration-guidance.md.
  • Sid establishment: Respond requires the sid before it runs, but no doc says who generates it or how; draft-21 suggests concatenating ephemeral random contributions from both parties. One sentence in README.md/docs/integration-guidance.md.
  • Identity distinctness: SelfID == PeerID is accepted silently and voids orientation binding (swap becomes undetectable). Document that the two identities must be distinct (behavior change would reopen the API freeze; docs-only is sufficient).
  • ErrConfirmationFailed triage: swapped identities, differing Context, divergent shared inputs, and wrong password are indistinguishable at runtime. Add the misconfiguration causes to the Error Triage section of docs/integration-guidance.md.
  • Runnable outer-binding example: the downgrade-protection recipe is prose-only; add an Example binding a negotiation commitment (including the PeerAssociatedData verification step) and optionally an identity-swap failure example.
  • CI byte-layout pointer: the normative 9-field LV layout exists only in buildCI (input.go) and TestBuildCIWireStability; docs/spec-matrix.md row for CI construction names neither file nor test. Add the field list or a pointer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions