# Documentation

`@udibo/oauth2` helps you add authentication and authorization to an
application. Choose who hosts sign-in first; that determines which parts of the
package you need.

## Use Udibo's identity service

Udibo hosts the sign-in flow and issues tokens. Your app handles its callback,
keeps its own session, and validates access to its API. You do not need to
implement password storage, MFA enrollment, or an authorization server.

You need a Udibo account; see [udibo.com](https://www.udibo.com/) for how to get
one. If you already have an account, start with
[the integration guide](https://www.udibo.com/docs/oauth2/guides/use-udibo).

Then read [API protection](https://www.udibo.com/docs/oauth2/guides/protect-an-api) and
[environment configuration](https://www.udibo.com/docs/oauth2/guides/deploy-across-environments).

## Host authorization for your own app

Your app owns its users, login pages, and persistent storage. The package
provides OAuth2 protocol handling and optional identity flows.

1. [Run a complete local example](https://www.udibo.com/docs/oauth2/quickstart).
2. [Configure your authorization server](https://www.udibo.com/docs/oauth2/guides/become-an-oauth-provider).
3. [Add login over your database](https://www.udibo.com/docs/oauth2/guides/add-login).
4. [Prepare the application for deployment](https://www.udibo.com/docs/oauth2/guides/production-deployment).

Add only the features your application needs:

| Feature                         | Guide                                                                      |
| ------------------------------- | -------------------------------------------------------------------------- |
| Social or enterprise OIDC login | [External sign-in](https://www.udibo.com/docs/oauth2/guides/social-sign-in)                               |
| TOTP and recovery codes         | [MFA](https://www.udibo.com/docs/oauth2/guides/add-mfa)                                                   |
| Passkeys (WebAuthn)             | [Passkeys](https://www.udibo.com/docs/oauth2/guides/add-passkeys)                                         |
| Email codes and magic links     | [Passwordless sign-in](https://www.udibo.com/docs/oauth2/guides/passwordless)                             |
| Existing password hashes        | [Password migration](https://www.udibo.com/docs/oauth2/guides/migrate-from-another-provider)              |
| Bot challenge for own login     | [CAPTCHA route example](https://www.udibo.com/docs/oauth2/guides/add-login#captcha-at-the-route-boundary) |

These guides explain application integrations. Hosted-service administration,
commercial platform architecture, and internal Udibo operations are outside this
package's documentation.

## Testing and reference

- [React integration](https://www.udibo.com/docs/oauth2/guides/react): session state, rendering guards, and
  app-owned forms.
- [Integration testing](https://www.udibo.com/docs/oauth2/guides/testing): route fixtures, persistent store
  contracts, and browser checks.

- [Local identity provider](https://www.udibo.com/docs/oauth2/guides/run-a-local-identity-provider): exercise
  your client against a local OAuth2/OIDC server without a hosted account.
- [Deployment checklist](https://www.udibo.com/docs/oauth2/guides/hardening-checklist): review the boundaries
  your chosen integration uses.
- [Extension reference](https://www.udibo.com/docs/oauth2/trigger-points): callback and storage contracts.
- [Partial-failure recovery](https://www.udibo.com/docs/oauth2/guides/recover-from-partial-failures): what a
  failing store leaves behind in each identity flow, and how to finish it.
- [Known limitations](https://www.udibo.com/docs/oauth2/known-limitations): supported behavior and constraints.
- [API reference](https://jsr.io/@udibo/oauth2/doc): exported types and methods.
- [Versioning and runtime support](https://www.udibo.com/docs/oauth2/stability).
- [Issue triage](https://www.udibo.com/docs/oauth2/triage) and [security disclosure](https://www.udibo.com/docs/oauth2/security).
- [Agent index](https://www.udibo.com/docs/oauth2/llms.txt) and [complete documentation](https://www.udibo.com/docs/oauth2/llms-full.txt).

Code fences show one of three things: a runnable command, a self-contained
example, or integration wiring that explicitly declares app-owned dependencies.
A `declare const` represents something your application must supply; it is not
an implementation to paste into production.