@udibo/oauth2 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Udibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @udibo/oauth2
+
+OAuth2 and OpenID Connect tools for TypeScript applications. Connect your app to
+Udibo's identity service, or host an authorization server for your own app. The
+package includes clients, authorization and resource servers, Hono middleware,
+React bindings, and optional login flows over your own database.
+
+**Udibo's managed identity service is in private beta.**
+[Join the waitlist](https://udibo.com). The self-hosted examples run locally
+without a hosted account.
+
+## Choose your path
+
+| Your application needs                      | Start here                                                                                                                |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Udibo to handle sign-in                     | [Use Udibo's identity service](docs/guides/use-udibo.md) — private-beta access required                                   |
+| Its own login and authorization server      | [Run the quickstart](docs/quickstart.md), then [host authorization for your app](docs/guides/become-an-oauth-provider.md) |
+| An API that accepts access tokens           | [Protect an API](docs/guides/protect-an-api.md)                                                                           |
+| A React application with server-held tokens | [Juniper starter](templates/juniper/README.md) or [React Router starter](templates/react-router/README.md)                |
+
+[Documentation index](docs/index.md) ·
+[API reference](https://jsr.io/@udibo/oauth2/doc) · [Examples](#examples) ·
+[Agent documentation](#for-coding-agents)
+
+## Install
+
+Requires Deno 2 for the development workflow:
+
+```sh
+deno add jsr:@udibo/oauth2@0.1.0
+```
+
+Import the part you use; there is no root barrel or default export:
+
+```ts
+import { BffClient, DirectClient } from "@udibo/oauth2/client";
+import { HonoBff } from "@udibo/oauth2/hono/bff";
+import { HonoResourceServer } from "@udibo/oauth2/hono/resource-server";
+```
+
+Version `0.1.0` is a pre-1.0 API. Minor releases may contain breaking changes;
+review the [stability policy](docs/stability.md) before upgrading.
+
+## How the pieces fit
+
+For a browser app, use a backend-for-frontend (BFF). The browser holds an
+HttpOnly session cookie; the BFF exchanges authorization codes and keeps access
+and refresh tokens on the server. `BffClient` connects the browser to the BFF,
+and the React adapter uses that same client.
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant App as Your app / BFF
+    participant Issuer as Udibo or your app's authorization server
+    participant API as Your API
+    Browser->>App: Start sign-in
+    App-->>Browser: Redirect to authorization endpoint
+    Browser->>Issuer: Sign in
+    Issuer-->>Browser: Redirect back with code and state
+    Browser->>App: Complete callback
+    App->>Issuer: Exchange code with PKCE and client authentication
+    Issuer-->>App: Tokens
+    App-->>Browser: Session cookie
+    Browser->>App: Request application data
+    App->>API: Access token
+    API-->>Browser: Application data, through the BFF
+```
+
+`DirectClient` is for a process that holds tokens: your backend, a CLI, a native
+app, or a public browser client. Supply a client secret only on the server. For
+a browser app with a backend, start with the BFF guide.
+
+`HonoResourceServer` validates access tokens and enforces scopes on API routes.
+`HonoAuthorizationServer` issues tokens when your app hosts its own
+authorization server. The framework-independent core accepts standard `Request`
+and `Response` objects; Hono adapters add routing and middleware.
+
+## Examples
+
+From a checkout of this repository:
+
+```sh
+deno ci
+deno task serve:app-with-own-auth
+```
+
+Open <http://localhost:8001/> and sign in as `user` / `password`. The
+[quickstart](docs/quickstart.md) explains what to try and which files to read.
+All demo credentials, in-memory stores, and local HTTP settings are for
+development.
+
+| Example                                                                         | Demonstrates                                                    |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| [Hono with own auth](examples/hono/app-with-own-auth/README.md)                 | App login, OAuth2 server, BFF, and protected API in one process |
+| [Hono with external auth](examples/hono/app-with-external-auth/README.md)       | Delegated sign-in, token introspection, and a BFF proxy         |
+| [Standalone API](examples/hono/api-service/README.md)                           | Bearer-token validation without a frontend                      |
+| [Juniper with own auth](examples/juniper/app-with-own-auth/README.md)           | Server-rendered React with application-owned login              |
+| [Juniper with external auth](examples/juniper/app-with-external-auth/README.md) | Server-rendered React with delegated sign-in                    |
+
+## Package entrypoints
+
+All paths below start with `@udibo/oauth2`. Each entrypoint has typed API docs
+and examples in the [reference](https://jsr.io/@udibo/oauth2/doc).
+
+| Subpath                      | Purpose                                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| `/client`                    | `BffClient`, `DirectClient`, token storage, discovery caching                                   |
+| `/server`                    | Shared models, errors, scope types, and service contracts                                       |
+| `/server/authorization`      | Authorization server, grants, token/code services, signing keys                                 |
+| `/server/resource`           | Resource server, introspection and JWKS token readers                                           |
+| `/server/public-suffix`      | Public Suffix List checks for optional wildcard redirect registration                           |
+| `/hono/authorization-server` | Hono authorization endpoints                                                                    |
+| `/hono/resource-server`      | Bearer authentication and scope middleware                                                      |
+| `/hono/bff`                  | BFF routes, server-held tokens, session and pending-login stores                                |
+| `/identity`                  | App-owned signup, login, password reset, email verification, passwordless, and protection hooks |
+| `/identity/mfa`              | TOTP, recovery codes, and MFA storage contract                                                  |
+| `/identity/external`         | Social and external OIDC sign-in for your own login pages                                       |
+| `/identity/migration`        | Verify imported password hashes and upgrade them at login                                       |
+| `/hono/identity`             | Hono routes for `IdentityService`                                                               |
+| `/hono/log`                  | Request logger and URL helper that redact every query value                                     |
+| `/react`                     | Context, hooks, authentication guards, and callback handling                                    |
+| `/react/components`          | Optional forms for login, signup, password reset, and MFA                                       |
+| `/crypto`                    | Random tokens, hashing, encoding, authenticated encryption                                      |
+| `/url`                       | Safe return paths and login continuation                                                        |
+| `/cli`                       | Local test identity provider and OIDC signing-key generation                                    |
+| `/testing`                   | In-memory fixtures and authorization-server test helpers                                        |
+| `/testing/contract`          | Tests for app-owned service and storage implementations                                         |
+| `/hono/bff/testing`          | BFF session fixtures and session-store contract tests                                           |
+| `/react/testing`             | Mock clients and providers for component tests                                                  |
+
+## Runtime support
+
+The library uses Web APIs. The complete suite runs on Deno. CI also builds an
+npm-format compatibility artifact and verifies 20 entrypoints with TypeScript
+and Node; this does not publish an npm package.
+
+| Surface                                     | Deno                  | Node                     | Browser                                     | Bun           |
+| ------------------------------------------- | --------------------- | ------------------------ | ------------------------------------------- | ------------- |
+| Clients and React                           | Tested, including SSR | Import/type smoke-tested | Intended for client code; no secrets        | Not verified  |
+| Server, identity, Hono, crypto, URL helpers | Tested                | Import/type smoke-tested | Server functionality belongs on the backend | Not verified  |
+| `/hono/bff/testing`, `/react/testing`       | Tested                | Import/type smoke-tested | React test helpers only                     | Not verified  |
+| `/testing`, `/testing/contract`             | Tested                | Not verified             | Not supported                               | Not verified  |
+| `/cli`                                      | Deno only             | Not supported            | Not supported                               | Not supported |
+
+See [stability](docs/stability.md#runtime-support) for the support boundary.
+
+## Before deploying
+
+Use the [application deployment guide](docs/guides/production-deployment.md) and
+[deployment checklist](docs/guides/hardening-checklist.md). Keep PKCE, state,
+confidential-client authentication, and CSRF checks enabled. Replace development
+stores with persistent implementations where needed, and run the exported
+contract tests against those implementations.
+
+Read [known limitations](docs/known-limitations.md) for token-revocation,
+cookie-session, OIDC, and optional-protection behavior. Identity feature
+examples apply to apps hosting their own login; Udibo clients use the hosted
+sign-in flow.
+
+## For coding agents
+
+Start with [llms.txt](llms.txt) for the task-to-guide map and integration rules.
+Use [llms-full.txt](llms-full.txt) when a single documentation download is
+useful. It is generated from the same guides developers read. Prefer the
+exported types and [extension reference](docs/trigger-points.md) when
+implementing a custom store or callback.
+
+## Contributing and security
+
+Run `deno task check` and `deno task test:all` before proposing changes. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for development conventions,
+[SECURITY.md](SECURITY.md) for private vulnerability reports, and
+[CHANGELOG.md](CHANGELOG.md) for release history.

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+`@udibo/oauth2` is security-critical software: it implements the OAuth 2.0 /
+OpenID Connect protocol surface and password-based identity flows. We take
+reports seriously and value the time of security researchers.
+
+> **Status note:** the package is not yet published to a public registry. Until
+> it is, the disclosure channel below is drafted and monitored, but the package
+> has no external users; the process activates fully at publish.
+
+## Supported versions
+
+| Version        | Supported                        |
+| -------------- | -------------------------------- |
+| latest `0.x`   | ✅ security fixes                |
+| older releases | ❌ upgrade to the latest release |
+
+Pre-1.0, security fixes land on the latest release only. From 1.0 on, the latest
+minor of the current major receives fixes, and the final minor of the previous
+major receives critical fixes for 6 months after a new major ships.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a security vulnerability.**
+
+Email **security@udibo.com** with:
+
+- A description of the vulnerability and the affected module/subpath (e.g.
+  `@udibo/oauth2/server`, `@udibo/oauth2/identity`).
+- Reproduction steps or a proof of concept.
+- The impact you believe it has (what an attacker gains).
+- Any suggested remediation, if you have one.
+
+You will receive an acknowledgment within **72 hours** and a substantive
+assessment within **7 days**. We ask that you give us **90 days** to remediate
+before public disclosure; we will credit you in the release notes unless you
+prefer otherwise. We do not operate a paid bounty program.
+
+## Scope
+
+In scope:
+
+- Protocol vulnerabilities (token leakage, redirect validation, PKCE bypass,
+  replay, open redirects, header trust).
+- Identity-flow vulnerabilities (enumeration oracles, timing oracles, throttle
+  or lockout bypass, token-flow weaknesses).
+- Cryptographic mistakes (signing, comparison, randomness).
+
+Out of scope:
+
+- Vulnerabilities in example apps' third-party dependencies (report upstream).
+- Misconfiguration of an app that consumes the library contrary to documented
+  guidance (though we welcome reports that the safe path is unclear — unclear
+  docs around a security control are treated as a docs bug with priority).
+
+## Design commitments
+
+- **The protocol defaults are the strict ones.** PKCE is required at both the
+  authorize and token endpoints (`requirePKCE: true`), `state` is required,
+  identity flows are enumeration-safe and timing-equalized, and the built-in
+  password policy runs whether or not you configure one. Relaxing any of these
+  is an explicit option you pass.
+- **The identity protections are opt-in objects, not defaults.** Rate limiting
+  and account lockout do **nothing** unless you construct and pass them:
+  `IdentityService` takes `rateLimiter` (and optional per-flow `rateLimiters`),
+  `lockout`, and — at the route layer — a `CaptchaProvider` you verify through
+  `verifyCaptcha`. An `IdentityService` built without them has no throttling and
+  no lockout. This is the single most consequential default in the identity
+  layer; treat wiring `rateLimiter` and `lockout` as part of deploying, not as
+  hardening you get to later. See
+  [Rate limiting, lockout, and password policy](docs/guides/production-deployment.md#rate-limiting-lockout-and-password-policy)
+  and the [hardening checklist](docs/guides/hardening-checklist.md).
+- **Honest gaps:** deviations from the specs, and defaults that trade safety for
+  compatibility, are documented in
+  [docs/known-limitations.md](docs/known-limitations.md), not hidden.
+- **No silent fixes:** security-relevant fixes are called out in the changelog
+  and release notes.

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,17 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};

package/esm/_dnt.polyfills.js

@@ -0,0 +1,15 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+export {};

package/esm/adapters/hono/_common.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Internal helpers shared by the Hono adapters.
+ *
+ * Not part of the public API — use {@link HonoResourceServer} or
+ * {@link HonoAuthorizationServer} instead. Keeping the `protect` /
+ * `authenticate` / `getContext` implementations in one place lets both
+ * adapter classes stay as direct subclasses of the server type they
+ * specialize (no composition / companion objects) without duplicating the
+ * Hono-specific plumbing.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import type { ClientInterface } from "../../models/client.js";
+import type { RequireConditions } from "../../models/authorization.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { AuthenticatedContext } from "../../server/resource-server.js";
+import { ResourceServer } from "../../server/resource-server.js";
+/**
+ * Key under which the authenticated OAuth2 context is stored on the Hono
+ * context. Namespaced to avoid collisions with other middleware.
+ */
+export declare const OAUTH2_CONTEXT_KEY: "@udibo/oauth2";
+/**
+ * Variables shape to plug into `Hono<{ Variables: ... }>` so
+ * `c.get("@udibo/oauth2")` / `server.getContext(c)` is typed.
+ */
+export interface HonoResourceServerVariables<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> {
+    /** The authenticated OAuth2 context set by the protect middleware. */
+    [OAUTH2_CONTEXT_KEY]: AuthenticatedContext<Client, User, S>;
+}
+/**
+ * Builds a Hono middleware that authenticates bearer tokens, stores the
+ * authenticated context at {@link OAUTH2_CONTEXT_KEY}, and on failure returns
+ * the server's auth error response.
+ */
+export declare function createProtectMiddleware<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, requiredScope?: S | string): MiddlewareHandler;
+/**
+ * Builds a Hono middleware that asserts the **already-authenticated** request
+ * (whose context a prior `protect` / `attachToken` set) carries
+ * `requiredScope`, without re-validating the token. Shared by both adapter
+ * classes' `requireScope` so the check and error stay identical to `protect`'s
+ * scope enforcement. `adapterName` names the class in the "context missing"
+ * developer error.
+ */
+export declare function createRequireScopeMiddleware<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, adapterName: string, requiredScope: S | string): MiddlewareHandler;
+/**
+ * Builds a Hono middleware that asserts the **already-authenticated** request
+ * (whose context a prior `protect` set) satisfies `conditions`, without
+ * re-validating the token. Shared by both adapter classes' `require` so the
+ * checks and errors stay identical to {@link ResourceServer.assertAuthorized}.
+ */
+export declare function createRequireMiddleware<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, adapterName: string, conditions: RequireConditions): MiddlewareHandler;
+/**
+ * Resolves a Hono {@link Context} or raw {@link Request} to a Request and
+ * calls the base {@link ResourceServer.authenticate} (bypassing any
+ * Context-accepting override). This is what both adapter classes'
+ * `authenticate` overrides end up calling.
+ */
+export declare function authenticateHonoRequest<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, c: Context | Request, requiredScope?: S | string): Promise<AuthenticatedContext<Client, User, S>>;
+/**
+ * Reads the authenticated OAuth2 context off the Hono context. Throws if
+ * `createProtectMiddleware` has not run first — the error message names the
+ * class the user invoked to make the fix obvious.
+ */
+export declare function readContext<Client extends ClientInterface, User, S extends AbstractScope>(c: Context, adapterName: string): AuthenticatedContext<Client, User, S>;

package/esm/adapters/hono/_common.js

@@ -0,0 +1,108 @@
+/**
+ * Internal helpers shared by the Hono adapters.
+ *
+ * Not part of the public API — use {@link HonoResourceServer} or
+ * {@link HonoAuthorizationServer} instead. Keeping the `protect` /
+ * `authenticate` / `getContext` implementations in one place lets both
+ * adapter classes stay as direct subclasses of the server type they
+ * specialize (no composition / companion objects) without duplicating the
+ * Hono-specific plumbing.
+ *
+ * @module
+ */
+import { ResourceServer } from "../../server/resource-server.js";
+/**
+ * Key under which the authenticated OAuth2 context is stored on the Hono
+ * context. Namespaced to avoid collisions with other middleware.
+ */
+export const OAUTH2_CONTEXT_KEY = "@udibo/oauth2";
+/**
+ * Builds a Hono middleware that authenticates bearer tokens, stores the
+ * authenticated context at {@link OAUTH2_CONTEXT_KEY}, and on failure returns
+ * the server's auth error response.
+ */
+export function createProtectMiddleware(server, requiredScope) {
+    return async (c, next) => {
+        try {
+            const ctx = await baseAuthenticate(server, c.req.raw, requiredScope);
+            c.set(OAUTH2_CONTEXT_KEY, ctx);
+            await next();
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+    };
+}
+/**
+ * Builds a Hono middleware that asserts the **already-authenticated** request
+ * (whose context a prior `protect` / `attachToken` set) carries
+ * `requiredScope`, without re-validating the token. Shared by both adapter
+ * classes' `requireScope` so the check and error stay identical to `protect`'s
+ * scope enforcement. `adapterName` names the class in the "context missing"
+ * developer error.
+ */
+export function createRequireScopeMiddleware(server, adapterName, requiredScope) {
+    return async (c, next) => {
+        const { scope } = readContext(c, adapterName);
+        try {
+            server.assertScope(scope, requiredScope);
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+        await next();
+    };
+}
+/**
+ * Builds a Hono middleware that asserts the **already-authenticated** request
+ * (whose context a prior `protect` set) satisfies `conditions`, without
+ * re-validating the token. Shared by both adapter classes' `require` so the
+ * checks and errors stay identical to {@link ResourceServer.assertAuthorized}.
+ */
+export function createRequireMiddleware(server, adapterName, conditions) {
+    return async (c, next) => {
+        const context = readContext(c, adapterName);
+        try {
+            server.assertAuthorized(context, conditions);
+        }
+        catch (error) {
+            return server.handleAuthError(error);
+        }
+        await next();
+    };
+}
+/**
+ * Resolves a Hono {@link Context} or raw {@link Request} to a Request and
+ * calls the base {@link ResourceServer.authenticate} (bypassing any
+ * Context-accepting override). This is what both adapter classes'
+ * `authenticate` overrides end up calling.
+ */
+export function authenticateHonoRequest(server, c, requiredScope) {
+    const request = c instanceof Request ? c : c.req.raw;
+    return baseAuthenticate(server, request, requiredScope);
+}
+/**
+ * Invokes the base {@link ResourceServer.authenticate} directly, bypassing
+ * any subclass override. Necessary because {@link HonoResourceServer}
+ * overrides `authenticate` to accept `Context | Request`; if this module
+ * called `server.authenticate(...)` the dispatch would land back on that
+ * override and recurse forever.
+ */
+function baseAuthenticate(server, request, requiredScope) {
+    // deno-lint-ignore no-explicit-any
+    const base = ResourceServer.prototype;
+    return base.authenticate.call(server, request, requiredScope);
+}
+/**
+ * Reads the authenticated OAuth2 context off the Hono context. Throws if
+ * `createProtectMiddleware` has not run first — the error message names the
+ * class the user invoked to make the fix obvious.
+ */
+export function readContext(c, adapterName) {
+    const ctx = c.get(OAUTH2_CONTEXT_KEY);
+    if (!ctx) {
+        throw new Error(`OAuth2 context missing; ensure ${adapterName}.protect() middleware ` +
+            `runs before this handler.`);
+    }
+    return ctx;
+}