docs / contributing

Contributing to AuthR

The AuthR protocol is in active development. Contributions to the spec, the Python reference, the TypeScript port, and the test vector suite are all welcome.

Ways to contribute

Design

Protocol spec

Propose amendments to authr-spec-v0.1. Open questions in §8 are the highest-priority discussion areas.

Open a GitHub Discussion →

Implementation

Python reference

The canonical implementation. pip install authr-protocol. Contributions to core primitives, test coverage, and documentation are all in scope.

See Python section below →

Test vectors

8–12 records, half passing and half failing for specific documented reasons. Other implementations verify against yours.

See test vectors section →

Implementation

TypeScript port

The playground runs on the TypeScript port. Parity with Python output is the standard. New invariant implementations welcome.

See TypeScript section →

Python reference package

The Python reference is the canonical AuthR implementation. It is the source of truth against which all other implementations are validated.

# Install from PyPI (when published) pip install authr-protocol # Install from source git clone https://github.com/identient/authr-protocol cd authr-protocol pip install -e ".[dev]" # Run the flagship scenario python -m authr.scenarios.cfo_wire # Run tests pytest tests/

The flagship scenario output should match the test vector at test-vectors/cfo-wire-root.json. If your implementation produces different output for the same inputs, that is a parity failure that needs resolution before merging.

# Package structure authr/ __init__.py # Public API: issueRoot, extendChain, verifyChain primitives.py # Author, Actor, Intent, Scope, Provenance, Drift issuing_authority.py # IssuingAuthority class verifier.py # Verifier class — all six invariants exceptions.py # ScopeExpansionError, AuthRError, etc. scenarios/ cfo_wire.py # Flagship runnable scenario test-vectors/ cfo-wire-root.json # Root record — must pass all invariants cfo-wire-hop.json # Hop record — scope narrowed scope-widening-attempt.json # Must fail invariant 4 expired-record.json # Must fail invariant 2 author-drift.json # Must fail invariant 3 chain-break.json # Must fail invariant 5

Test vectors

Test vectors are AuthR records in JSON format that implementations use to verify correctness. The suite must contain 8–12 records: at least half must be intentionally failing, each failing for a specific, documented invariant violation.

Vector file	Expected result	Reason	Invariant
`cfo-wire-root.json`	PASS	Valid root record, all fields correct	`All 6`
`cfo-wire-hop.json`	PASS	Valid hop, scope correctly narrowed	`All 6`
`low-risk-auto.json`	PASS	Low-risk record, auto-approve path	`All 6`
`multi-hop-chain.json`	PASS	Three-hop chain, all scopes valid	`All 6`
`scope-widening-attempt.json`	FAIL	wire.cancel added — not in parent scope	`Inv.4`
`expired-record.json`	FAIL	expires_at is in the past	`Inv.2`
`author-drift.json`	FAIL	author.id changes at hop 2	`Inv.3`
`chain-break.json`	FAIL	Hop does not reference parent authr_id	`Inv.5`
`correlation-mismatch.json`	FAIL	correlation_id differs at hop 2	`Inv.6`
`bad-signature.json`	FAIL	Signature value tampered	`Inv.1`

To submit a new test vector, open a PR with the JSON file and a companion .meta.json file documenting the expected result, the violated invariant (if failing), and the reason.

TypeScript port

The TypeScript port lives in src/lib/authr.ts in this repository. It must maintain output parity with the Python reference for all test vectors. To verify parity:

# Run parity tests npm run test:parity # The parity test suite runs all test vectors through # both the Python and TypeScript implementations and # compares the verification results. # Signature values will differ (different mock seeds) # but all invariant pass/fail results must match.

Spec contributions

The spec is in active discussion. The highest-priority open questions from §8 are:

1Cross-domain federation — OAuth Federation as the likely path. Looking for architects with federation experience.

2Multi-author records — committee authorship needs a concrete data model proposal.

3Wire format — JSON + JWS vs CBOR/COSE. Evaluation criteria needed for constrained environments.

4Revocation propagation — event-driven via Kafka is the v0.1 assumption. Edge cases need enumeration.

To propose a spec change, open a GitHub Discussion with the label spec-proposal. Include the affected section, the proposed change, and the rationale. Breaking changes to v0.1 require consensus from at least two independent implementors.

Review process

Open an issue or discussion

Before writing code, describe the change you want to make. For spec changes, use a GitHub Discussion. For implementation bugs, use a GitHub Issue.

Fork and branch

Fork the repository. Create a branch named feat/description, fix/description, or spec/description.

Write tests first

For implementation changes, add a failing test vector or unit test before writing the fix. For spec changes, describe what a conforming implementation must do.

Open a PR

PRs must pass all test vectors and parity tests. Include a description of the change, the motivation, and any open questions.

Review and merge

PRs require one review from a maintainer. Breaking changes require two independent implementor reviews. The spec maintainer has final say on spec PRs.