Skip to content

Defer profile-kit and proof-exchange from the first SDK release surface #51

Description

@bordumb

Decision

Keep the first Auths release candidate deliberately SDK-first.

First-class supported package roots

  • crates.io: auths
  • crates.io: auths-sdk
  • npm: @auths-dev/sdk
  • PyPI: auths
  • the source archive and immutable assurance/evidence bundle

The two supported Rust roots require a 28-crate normal-dependency closure on
crates.io. auths is the thin public facade, auths-sdk is the high-level SDK,
and auths-proof remains a bounded proof-protocol component within that
closure. The existing crates.io auths and auths-sdk coordinates belong to
the experimental predecessor line and continue only through an intentional
major-version transition. The supporting crates are registry-visible
implementation dependencies, not 28 separately promised top-level SDKs. The
release manifest must generate and verify the exact closure from the candidate
revision.

The TypeScript package owns the prepared WASM boundary. The Python package owns
its prepared native wheels. Their Rust build crates are not additional
first-class crates.io roots.

The authoritative coordinate and predecessor-disposition inventory is
release/public-naming.toml, governed by Issue #54 and AP-SPEC-034.

Deferred public roots

  • auths-profile-kit
  • auths-proof-exchange
  • proof-exchange adapters for memory, file, HTTPS, Iroh, TCP, and Unix sockets
  • domain integration crates
  • demos, benchmarks, testkits, fuzz crates, internal tools, CLIs, and hosted services

This issue records a compatibility deferral. It does not authorize Phase 10,
package publication, transport expansion, or a hosted dependency.

Why defer

  • The product strategy says to establish a solid SDK before deciding which
    lower-level extension surfaces deserve permanent compatibility promises.
  • Publishing a technically available crate turns its API, features, dependency
    graph, security boundary, and documentation into a consumer commitment.
  • Transport remains plumbing. Deferring the transport facade does not couple
    Auths semantics to HTTP, Iroh, or any other carrier.
  • We need user evidence about whether developers extend profiles, exchange
    proofs directly, or stay within the high-level SDK.

Follow-up ideas

Profile extension kit

  • Collect concrete external profile-authoring use cases
  • Freeze profile ownership and closed-gateway rules
  • Define stable conformance fixtures and negative tests for third-party profiles
  • Decide whether profile authors need a public Rust crate, generated bindings, or SDK-only helpers
  • Prove that adding a profile does not expand shared receipt unions or force unrelated consumers to change
  • Document semantic-versioning and support obligations

Proof exchange

  • Validate demand for direct proof exchange outside the SDK
  • Keep protocol semantics transport-neutral and adapter-owned
  • Decide the minimum supported transport set from evidence, not implementation availability
  • Define per-adapter resource limits, timeout/cancellation behavior, replay handling, and conformance
  • Decide whether Iroh belongs in the first extension preview or remains an optional experiment
  • Test offline, headless, on-prem, macOS, Linux, and Windows behavior
  • Publish only adapters whose dependency and security policies pass the release gate

Release readiness

  • Produce an exact dependency-closure diff against the SDK-first RC
  • Assign public API and security owners
  • Add package dry-runs, consumer smoke tests, SBOM coverage, and provenance subjects
  • Add exact assurance claims and exclusions for the new subjects
  • Obtain the separately required phase and owner approvals

Reconsideration evidence

Reconsider the deferral only when at least one of these is true:

  • multiple independent SDK users need the same extension boundary;
  • an MCP or design-partner integration cannot remain cleanly SDK-owned;
  • the transport facade materially improves an on-prem or headless deployment;
  • maintaining private crates creates more compatibility risk than publishing a
    bounded surface; or
  • the relevant later-phase specification explicitly requires the package.

Any follow-up implementation must be split into its own bounded PR units and
must not be folded into the first-RC closure as incidental scope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions