@pondoknusa/auth-oauth

OAuth2 authorization server for Pondoknusa — authorization code with mandatory PKCE, client credentials, and refresh tokens.

Most apps only consume OAuth; this package is for the other direction. It turns a Pondoknusa app into an identity provider, so first-party and third-party clients can obtain scoped bearer tokens on behalf of your users while reusing the guards and Eloquent user provider from @pondoknusa/auth and your existing database connection. Tokens are opaque random secrets by default, or quantum-safe signed tokens when signing via @pondoknusa/crypto is enabled — the OAuthServer reads the request path and the crypto config, so the app still supplies the storage and keys.

Part of the Pondoknusa framework — a TypeScript-native full-stack framework built on standard Web APIs. Requires Node.js ≥ 26.

Install

npm install @pondoknusa/auth-oauth @pondoknusa/database

Quick start

Scaffold the server, register a client, and migrate:

pondoknusa oauth:install
pondoknusa oauth:client:create "My App" --redirect=http://127.0.0.1:3000/callback
pondoknusa migrate

oauth:install registers OAuthServerServiceProvider in src/main.ts and writes config/oauthServer.ts. Protect your own routes with the auth:oauth middleware alias:

import { Route } from '@pondoknusa/core';
import { Response } from '@pondoknusa/http';

Route.middleware('auth:oauth').get('/api/external', () => Response.json({ ok: true }));

Issued tokens are accepted by the server's standard endpoints — GET/POST /oauth/authorize, POST /oauth/token, POST /oauth/revoke (RFC 7009), and GET /oauth/userinfo. Grant types:

| Grant | Use case | |-------|----------| | authorization_code | User-delegated access; PKCE is required for public clients | | client_credentials | Machine-to-machine | | refresh_token | Long-lived sessions |

To issue quantum-safe signed access tokens (oat_<payload>.<signature>) instead of opaque secrets, provide an ML-DSA key pair and set crypto.oauth.signTokens in config/crypto.ts, or configure oauthServer.tokenSigning directly. Legacy opaque tokens keep working when signing is disabled.

Related packages

• @pondoknusa/auth — the guards and user provider this server reuses for user-delegated grants.
• @pondoknusa/crypto — ML-DSA and SLH-DSA signing for access tokens.
• @pondoknusa/core — the service providers and facades the server registers into.
• @pondoknusa/database — the peer package holding the client, code, and token tables.

Documentation

• Authentication guide — see the OAuth2 authorization server section.
• Package reference
• Source

MIT © Pondoknusa Contributors