Vord

Enhancement Proposal

Proposal: SDKs, quickstarts, and developer experience

M4 is the first release strangers are meant to run, and adoption is decided in the first thirty minutes. This specs the adoption surface: which SDKs exist (and, more pointedly, which do not), quickstarts as tested artifacts, and the local dev loop. The conformance posture (ADR-0003 / ADR-0025) already made the biggest call: relying parties need no Vord SDK.

Motivation

An IdP is adopted by the developer wiring up login long before any admin evaluates it, and the incumbents' moat is quickstart quality. Vord's counter-pitch is stronger than parity — your existing OIDC library already works — but only if the first thirty minutes prove it.

Design

  • Relying parties integrate with stock OIDC libraries. Standard token formats (ADR-0003) and the conformance posture (ADR-0025) are the contract; quickstarts demonstrate unmodified openid-client, Spring Security, and friends against Vord. Needing a Vord SDK here would be a conformance bug, not a feature gap.
  • The SDK story is two things. (i) The thick service-side SDK: it propagates consistency tokens (ADR-0004) and ships the local verifier — ADR-0044 declined mandatory introspection, so the SDK carries Vör's verification rules in-process, never reading a strong domain on the hot path (rule 1, ADR-0001 / ADR-0010). (ii) Management-API clients over the admin API.
  • Language priority: the Rust reference, then TypeScript/Node and one JVM language — where the workforce/CIAM integrator mass is. Generated from the API definitions (ADR-0021's gRPC/REST) wherever possible; hand-written only for the verifier core.
  • Quickstarts are tested artifacts: every quickstart runs in CI against the single-binary dev profile (ADR-0024) — one binary, instant start, no compose thicket. The dev profile is the DX substrate, and a quickstart that fails CI blocks the release.
  • The CLI is the dev loop: ADR-0021's thin CLI doubles as local tooling — create a tenant and a client, mint test tokens, iterate.
  • Docs are versioned with the code — the existing docs discipline extends to quickstarts and SDK reference, so docs and binaries cannot skew.

Alternatives considered

  • SDK-for-everything (a Vord SDK per framework as the primary integration path) — rejected: stock-OIDC-first is the point of the conformance posture (ADR-0025), and vendor-SDK lock-in is the pattern Vord exists to avoid.
  • Docs-site-only quickstarts — rejected: untested quickstarts rot; only CI-run quickstarts stay true.

Graduation criteria

A developer reaches a verified login against the dev profile with a stock OIDC library in minutes, following a quickstart that passed CI; the thick SDK round-trips a consistency token and verifies locally with the core down (ADR-0010's independence test, taken from the SDK's seat); and management clients are generated from the API definitions for the priority languages.

Backward compatibility

Additive: SDKs and quickstarts sit on published contracts — tokens (ADR-0003) and the admin API (ADR-0021). The thick SDK versions with the consistency-token contract (ADR-0004); a relying party on stock OIDC is unaffected by SDK releases by construction.

Open questions

  • Which JVM language leads: Java (integrator mass) or Kotlin (one artifact serves both, better ergonomics).
  • Whether the local verifier ships as one multi-language core (FFI over the Rust crate — one implementation to get right, at the cost of FFI toolchain pain) or per-language implementations (idiomatic, but N chances to diverge).