Thank you for helping external platforms recognize and safely authorize Realmroot Agents.
- Search existing issues and provider proposals.
- For a new provider, open a provider proposal before implementation.
- For security vulnerabilities, follow SECURITY.md instead of opening a public issue.
- Keep credentials, customer data, and personal provider accounts out of tests, fixtures, issues, and pull requests.
A proposal must document evidence from the provider's official contract or documentation for:
- native actor types and stable identifiers;
- whether the actor is visible in product UI, audit logs, or both;
- installation, authorization, and administrator requirements;
- credential issuance, expiry, rotation, and revocation;
- discoverable Resource types and selection boundaries;
- permissions and their mapping to operations;
- webhook or polling signals for permission and installation changes;
- provider retry and idempotency semantics that the proxy must preserve;
- transformations required beyond transparent forwarding;
- known product-tier, review, marketplace, or compliance requirements;
- a date-stamped matrix for every stable capability ID in the Agent-native Resource Server Profile, with official evidence and an explicit distinction between native support, adapter bridging, missing support, and non-applicability;
- the observable condition under which the adapter can be deprecated.
A provider that only supports a shared application actor is still welcome, but
must declare provider-delegated identity rather than presenting display
attribution as a native Agent principal.
Contributions that help a platform adopt the native protocol profile are as valuable as adapter implementations. The project prefers a smaller removable adapter and a credible direct-integration path over a permanent feature-complete proxy.
- Implement every Adapter as a standard external OAuth authorization server and protected Resource. Do not add an Adapter-specific authorization model or private account-connection protocol to Realmroot.
- Keep provider OAuth, credentials, refresh, revocation, lifecycle state, permission mapping, and API execution inside the provider module.
- Adding a provider must require Realmroot configuration only, not a Realmroot core-code change.
- Start with one complete provider journey and its proof.
- Keep canonical contracts owned by the application behavior that consumes them; adapters implement those contracts.
- Preserve the provider's original API instead of adding adapter-owned business operations or response schemas.
- Keep each provider implementation isolated; adding or fixing one provider must not require changes inside another provider directory.
- Do not expose provider SDK types, token formats, or HTTP response shapes to the core.
- Validate at Agent, provider, network, environment, and persistence boundaries. Do not add internal fallback behavior for impossible states.
- Fail closed on authorization uncertainty and revocation.
- Never downgrade DPoP to bearer authentication on the Agent-facing boundary.
- Never log or return provider credentials.
- Add dependencies only when they remove meaningful complexity.
Pull requests should be focused and include:
- the observable behavior being added or changed;
- the identity and authorization semantics involved;
- tests at the cheapest layer that proves the behavior;
- provider documentation supporting any capability claim;
- security and revocation implications;
- manual review steps for an isolated provider test environment;
- updates to the provider README, capability manifest, and roadmap when applicable.
Maintainers may ask to split a provider contribution when identity, authorization, discovery, and operation changes cannot be reviewed safely as one unit.
Run the repository's documentation checks before submitting a documentation- only change:
ruby scripts/check-docs.rbUse clear, imperative commits. Conventional Commit prefixes are encouraged:
feat(linear): add app actor installation
fix(github): reject removed repositories
docs(cloudflare): document audit actor mapping
Every material change is reviewed on two axes:
- Outcome: it provides the requested provider behavior without overstating identity fidelity.
- Engineering: it preserves security boundaries, failure semantics, observability, tests, compatibility, and maintainability.
By contributing, you certify that you have the right to submit the work under this project's Apache-2.0 license. Sign off each commit with:
git commit -sThe sign-off records the Developer Certificate of Origin statement available at https://developercertificate.org/.