std/oauth

OAuth authentication middleware for Val Town vals.

Features

OAuth 2.0 Authorization Code flow with PKCE
Dynamic client registration
Encrypted session cookies (stateless)
No database required

Usage

Create val
/** @jsxImportSource https://esm.sh/hono/jsx */
import { Hono } from "https://esm.sh/hono";
import {
  getOAuthUserData,
  oauthMiddleware,
} from "https://esm.town/v/std/oauth/middleware.ts";

const app = new Hono();

app.get("/", async (c) => {
  const session = await getOAuthUserData(c.req.raw);

  return c.html(
    <html>
      <body>
        {session?.user
          ? <p>Logged in as {session.user.username}</p>
          : <a href="/auth/login">Log in</a>}
      </body>
    </html>,
  );
});

// Simple usage with defaults
export default oauthMiddleware(app.fetch);

API

`oauthMiddleware(appFetch)` or `oauthMiddleware(options, appFetch)`

Wraps your application to handle OAuth routes. Supports two calling styles:

Handler only (backwards compatible): oauthMiddleware(appFetch)
Options first (Deno.serve style): oauthMiddleware(options, appFetch)

Options:

scopes?: string[] - OAuth scopes (default: ["openid", "offline_access", "profile", "user_rw"])
clientName?: string - OAuth client name

Auto-handled routes:

/auth/login - Start OAuth flow
/auth/callback - OAuth callback
/auth/logout - Clear session

`getOAuthUserData(req: Request)`

Extract user data from session cookie.

Returns: SessionData | null

interface SessionData {
  user: {
    id: string;
    bio: string | null;
    email: string | null;
    links: {
      self: string;
      profileImageUrl: string | null;
    };
    tier: "free" | "pro" | null;
    type: "user" | "org";
    url: string;
    username: string | null;
  };
  accessToken: string;
  refreshToken?: string;
  idToken?: string;
  expiresAt: number;
}

Environment Variables

OAUTH_STATE_ENCRYPTION_KEY (optional) - Encryption key for state and sessions
- Auto-generated if not set
- Set manually (e.g., openssl rand -base64 32) for better performance

How It Works

User clicks /auth/login
Redirects to Val Town OAuth
User authorizes
Callback receives code, exchanges for tokens
User data fetched from /v1/me API using access token
Session encrypted and stored in cookie
Use getOAuthUserData(req) to access user data

Sessions last 30 days and are stored as encrypted cookies (no server-side storage).

std

oauth

Login with Val Town OAuth Middleware