@sentropic/auth-hono 0.2.1 → 0.4.0

package/src/oauth/dpop.ts

@@ -0,0 +1,93 @@
+import {
+  calculateJwkThumbprint,
+  decodeProtectedHeader,
+  importJWK,
+  jwtVerify,
+  type JWK,
+  type JWTPayload,
+} from 'jose';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { sha256Base64url } from './crypto-utils.js';
+
+export interface VerifyDpopProofOptions {
+  accessToken?: string;
+  htm: string;
+  htu: string;
+  iatSkewSeconds?: number;
+  ports: AuthHonoPorts;
+  proof: string;
+}
+
+export interface VerifiedDpopProof {
+  jkt: string;
+  jti: string;
+}
+
+export class OAuthDpopProofError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OAuthDpopProofError';
+  }
+}
+
+export const verifyOAuthDpopProof = async (
+  options: VerifyDpopProofOptions
+): Promise<VerifiedDpopProof> => {
+  const header = decodeProtectedHeader(options.proof);
+  const publicJwk = header.jwk as JWK | undefined;
+  if (!publicJwk || !header.alg || header.typ !== 'dpop+jwt') {
+    throw new OAuthDpopProofError('DPoP proof header is invalid.');
+  }
+
+  const key = await importJWK(publicJwk, header.alg);
+  const { payload } = await jwtVerify(options.proof, key);
+  await validateDpopPayload(payload, options);
+
+  const expiresAt = options.ports.clock.addSeconds(
+    options.ports.clock.now(),
+    options.iatSkewSeconds ?? 60
+  );
+  const recorded = await options.ports.oauthStateStore.recordDpopJti(String(payload.jti), expiresAt);
+  if (!recorded) {
+    throw new OAuthDpopProofError('DPoP proof jti was already used.');
+  }
+
+  return {
+    jkt: await calculateJwkThumbprint(publicJwk),
+    jti: String(payload.jti),
+  };
+};
+
+const validateDpopPayload = async (
+  payload: JWTPayload,
+  options: VerifyDpopProofOptions
+): Promise<void> => {
+  if (payload.htm !== options.htm.toUpperCase()) {
+    throw new OAuthDpopProofError('DPoP htm claim does not match the request method.');
+  }
+  if (payload.htu !== options.htu) {
+    throw new OAuthDpopProofError('DPoP htu claim does not match the request URL.');
+  }
+  if (!payload.jti || typeof payload.jti !== 'string') {
+    throw new OAuthDpopProofError('DPoP jti claim is required.');
+  }
+  if (typeof payload.iat !== 'number') {
+    throw new OAuthDpopProofError('DPoP iat claim is required.');
+  }
+
+  const nowSeconds = Math.floor(options.ports.clock.now().getTime() / 1000);
+  if (Math.abs(payload.iat - nowSeconds) > (options.iatSkewSeconds ?? 60)) {
+    throw new OAuthDpopProofError('DPoP iat claim is outside the allowed skew.');
+  }
+
+  if (options.accessToken) {
+    await validateAth(payload, options.accessToken);
+  }
+};
+
+const validateAth = async (payload: JWTPayload, accessToken: string): Promise<void> => {
+  if (payload.ath !== (await sha256Base64url(accessToken))) {
+    throw new OAuthDpopProofError('DPoP ath claim does not match the access token.');
+  }
+};

package/src/oauth/http-utils.ts

@@ -0,0 +1,58 @@
+import type { Context } from 'hono';
+
+export const appendParams = (
+  target: string,
+  params: Record<string, string | null | undefined>,
+  baseUrl: string
+): string => {
+  const url = new URL(target, baseUrl);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== null && value !== undefined) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+};
+
+export const oauthJsonError = (
+  c: Context,
+  status: 400 | 401,
+  code: string,
+  message: string
+): Response =>
+  c.json(
+    {
+      error: {
+        code,
+        message,
+      },
+    },
+    status
+  );
+
+export const redirectWithOAuthError = (
+  redirectUri: string,
+  code: string,
+  state: string | null,
+  baseUrl: string
+): Response =>
+  Response.redirect(
+    appendParams(
+      redirectUri,
+      {
+        error: code,
+        state,
+      },
+      baseUrl
+    ),
+    302
+  );
+
+export const redirectOrJson = (c: Context, redirectTo: string): Response => {
+  const accept = c.req.header('accept') ?? '';
+  if (accept.includes('application/json')) {
+    return c.json({ redirectTo });
+  }
+
+  return c.redirect(redirectTo, 302);
+};

package/src/oauth/introspect-handler.ts

@@ -0,0 +1,88 @@
+import type { Context } from 'hono';
+import type { JWTPayload } from 'jose';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { oauthJsonError } from './http-utils.js';
+import { createJwksService } from './jwks-service.js';
+
+export interface OAuthIntrospectHandlerOptions {
+  issuer: string;
+  ports: AuthHonoPorts;
+}
+
+export const createOAuthIntrospectHandler =
+  (options: OAuthIntrospectHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const authenticated = await authenticateIntrospectionClient(c, options.ports);
+    if (authenticated instanceof Response) return authenticated;
+
+    const form = new URLSearchParams(await c.req.text());
+    const token = form.get('token');
+    if (!token) return c.json({ active: false });
+
+    const payload = await verifyToken(options, token);
+    if (!payload?.jti) return c.json({ active: false });
+
+    const meta = await options.ports.oauthStateStore.findTokenMeta(payload.jti);
+    if (
+      !meta ||
+      meta.expiresAt <= options.ports.clock.now() ||
+      (await options.ports.oauthStateStore.isTokenRevoked(payload.jti))
+    ) {
+      return c.json({ active: false });
+    }
+
+    return c.json({
+      active: true,
+      aud: meta.audience,
+      client_id: meta.clientId,
+      ...(meta.dpopJkt ? { cnf: { jkt: meta.dpopJkt } } : {}),
+      exp: toEpochSeconds(meta.expiresAt),
+      iat: typeof payload.iat === 'number' ? payload.iat : undefined,
+      jti: meta.jti,
+      scope: meta.scope,
+      sub: meta.userId,
+      token_type: meta.tokenType,
+    });
+  };
+
+const authenticateIntrospectionClient = async (
+  c: Context,
+  ports: AuthHonoPorts
+): Promise<true | Response> => {
+  const authorization = c.req.header('authorization');
+  if (!authorization?.startsWith('Basic ')) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client authentication is required.');
+  }
+
+  const decoded = atob(authorization.slice('Basic '.length));
+  const separator = decoded.indexOf(':');
+  const clientId = separator >= 0 ? decoded.slice(0, separator) : decoded;
+  const secret = separator >= 0 ? decoded.slice(separator + 1) : '';
+  const client = await ports.oauthStateStore.findClient(clientId);
+  if (!client?.clientSecretHash || (await ports.tokens.hashSecret(secret)) !== client.clientSecretHash) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client authentication failed.');
+  }
+
+  return true;
+};
+
+const verifyToken = async (
+  options: OAuthIntrospectHandlerOptions,
+  token: string
+): Promise<JWTPayload | null> => {
+  try {
+    const jwks = createJwksService({ clock: options.ports.clock, jwksPort: options.ports.jwks });
+    const result = await jwks.verifyJwt(token, {
+      currentDate: options.ports.clock.now(),
+      issuer: trimTrailingSlash(options.issuer),
+    });
+    return result.payload;
+  } catch {
+    return null;
+  }
+};
+
+const toEpochSeconds = (date: Date): number => Math.floor(date.getTime() / 1000);
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/u, '');

package/src/oauth/jwks-service.ts

@@ -0,0 +1,103 @@
+import {
+  decodeProtectedHeader,
+  importJWK,
+  jwtVerify,
+  SignJWT,
+  type JWTVerifyOptions,
+  type JWTVerifyResult,
+  type JWTPayload,
+} from 'jose';
+
+import type { AuthHonoClockPort } from '../ports.js';
+import type { JwksPort } from './state-store-types.js';
+
+export interface CreateJwksServiceOptions {
+  clock: AuthHonoClockPort;
+  jwksPort: JwksPort;
+}
+
+export interface JwksSignOptions {
+  audience?: string | string[];
+  expiresAt?: Date;
+  issuer?: string;
+  jti?: string;
+  subject?: string;
+  type?: string;
+}
+
+export interface PublicJwks {
+  keys: Array<Record<string, unknown>>;
+}
+
+export interface JwksService {
+  getPublicJwks(): Promise<PublicJwks>;
+  signJwt(payload: JWTPayload, options?: JwksSignOptions): Promise<string>;
+  verifyJwt<T extends JWTPayload = JWTPayload>(
+    jwt: string,
+    options?: JWTVerifyOptions
+  ): Promise<JWTVerifyResult<T>>;
+}
+
+export const createJwksService = ({ clock, jwksPort }: CreateJwksServiceOptions): JwksService => ({
+  async getPublicJwks() {
+    const keys = await jwksPort.listPublicKeys();
+
+    return {
+      keys: keys.map((key) => {
+        const { d: _privateExponent, ...publicJwk } = key.publicJwk;
+        return {
+          ...publicJwk,
+          alg: key.alg,
+          crv: key.crv,
+          kid: key.kid,
+          kty: publicJwk.kty,
+          status: key.active ? 'active' : 'rotated',
+          use: 'sig',
+        };
+      }),
+    };
+  },
+
+  async signJwt(payload, options = {}) {
+    const activeKey = await jwksPort.getActiveKey();
+    if (!activeKey) {
+      throw new Error('No active JWKS signing key is configured.');
+    }
+    if (!activeKey.privateKey) {
+      throw new Error(`Active JWKS signing key ${activeKey.kid} has no private key material.`);
+    }
+
+    let jwt = new SignJWT(payload).setProtectedHeader({
+      alg: activeKey.alg,
+      kid: activeKey.kid,
+      ...(options.type ? { typ: options.type } : {}),
+    });
+
+    jwt = jwt.setIssuedAt(toEpochSeconds(clock.now()));
+    if (options.audience) jwt = jwt.setAudience(options.audience);
+    if (options.expiresAt) jwt = jwt.setExpirationTime(toEpochSeconds(options.expiresAt));
+    if (options.issuer) jwt = jwt.setIssuer(options.issuer);
+    if (options.jti) jwt = jwt.setJti(options.jti);
+    if (options.subject) jwt = jwt.setSubject(options.subject);
+
+    return jwt.sign(activeKey.privateKey);
+  },
+
+  async verifyJwt(jwt, options = {}) {
+    const protectedHeader = decodeProtectedHeader(jwt);
+    const kid = protectedHeader.kid;
+    if (!kid) {
+      throw new Error('JWT protected header is missing kid.');
+    }
+
+    const key = await jwksPort.findKeyByKid(kid);
+    if (!key) {
+      throw new Error(`Unknown JWKS kid: ${kid}`);
+    }
+
+    const publicKey = await importJWK(key.publicJwk, key.alg);
+    return jwtVerify(jwt, publicKey, options);
+  },
+});
+
+const toEpochSeconds = (date: Date): number => Math.floor(date.getTime() / 1000);

package/src/oauth/revoke-handler.ts

@@ -0,0 +1,70 @@
+import type { Context } from 'hono';
+import { decodeJwt } from 'jose';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { OAuthDpopProofError, verifyOAuthDpopProof } from './dpop.js';
+import { oauthJsonError } from './http-utils.js';
+
+export interface OAuthRevokeHandlerOptions {
+  dpopIatSkewSeconds?: number;
+  ports: AuthHonoPorts;
+}
+
+export const createOAuthRevokeHandler =
+  (options: OAuthRevokeHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const form = new URLSearchParams(await c.req.text());
+    const token = form.get('token');
+    if (!token) return oauthJsonError(c, 400, 'invalid_request', 'token is required.');
+
+    const jti = decodeTokenJti(token);
+    if (!jti) return c.json({ success: true });
+
+    const meta = await options.ports.oauthStateStore.findTokenMeta(jti);
+    if (meta?.dpopJkt) {
+      const dpop = await validateRevokeDpop(c, options, token, meta.dpopJkt);
+      if (dpop instanceof Response) return dpop;
+    }
+
+    await options.ports.oauthStateStore.revokeToken(jti);
+    return c.json({ success: true });
+  };
+
+const validateRevokeDpop = async (
+  c: Context,
+  options: OAuthRevokeHandlerOptions,
+  accessToken: string,
+  expectedJkt: string
+): Promise<null | Response> => {
+  const proof = c.req.header('dpop');
+  if (!proof) return oauthJsonError(c, 400, 'invalid_dpop_proof', 'DPoP proof is required.');
+
+  try {
+    const verified = await verifyOAuthDpopProof({
+      accessToken,
+      htm: 'POST',
+      htu: c.req.url,
+      iatSkewSeconds: options.dpopIatSkewSeconds,
+      ports: options.ports,
+      proof,
+    });
+    if (verified.jkt !== expectedJkt) {
+      return oauthJsonError(c, 400, 'invalid_dpop_proof', 'DPoP proof key does not match the token.');
+    }
+    return null;
+  } catch (error) {
+    if (error instanceof OAuthDpopProofError) {
+      return oauthJsonError(c, 400, 'invalid_dpop_proof', error.message);
+    }
+    throw error;
+  }
+};
+
+const decodeTokenJti = (token: string): string | null => {
+  try {
+    const payload = decodeJwt(token);
+    return typeof payload.jti === 'string' ? payload.jti : null;
+  } catch {
+    return null;
+  }
+};

package/src/oauth/router.ts

@@ -0,0 +1,42 @@
+import { Hono } from 'hono';
+
+import { createOAuthAuthorizeHandler, type OAuthAuthorizeHandlerOptions } from './authorize-handler.js';
+import {
+  createOAuthConsentDecisionHandler,
+  createOAuthConsentDetailsHandler,
+} from './consent-decision-handler.js';
+import { createOAuthIntrospectHandler } from './introspect-handler.js';
+import { createOAuthRevokeHandler } from './revoke-handler.js';
+import { createOAuthTokenHandler } from './token-handler.js';
+import { createOAuthUserInfoHandler } from './userinfo-handler.js';
+
+export interface CreateOAuthRouterOptions extends OAuthAuthorizeHandlerOptions {
+  authorizationCodeTtlSeconds?: number;
+  routePrefix?: string;
+}
+
+export const createOAuthRouter = (options: CreateOAuthRouterOptions): Hono => {
+  const router = new Hono();
+  const prefix = normalizeRoutePrefix(options.routePrefix ?? '/oauth');
+
+  router.get(joinRoutePath(prefix, '/authorize'), createOAuthAuthorizeHandler(options));
+  router.get(joinRoutePath(prefix, '/consent'), createOAuthConsentDetailsHandler(options));
+  router.post(joinRoutePath(prefix, '/consent/decision'), createOAuthConsentDecisionHandler(options));
+  router.post(joinRoutePath(prefix, '/token'), createOAuthTokenHandler(options));
+  router.get(joinRoutePath(prefix, '/userinfo'), createOAuthUserInfoHandler(options));
+  router.post(joinRoutePath(prefix, '/userinfo'), createOAuthUserInfoHandler(options));
+  router.post(joinRoutePath(prefix, '/revoke'), createOAuthRevokeHandler(options));
+  router.post(joinRoutePath(prefix, '/introspect'), createOAuthIntrospectHandler(options));
+
+  return router;
+};
+
+const normalizeRoutePrefix = (prefix: string): string => {
+  if (!prefix || prefix === '/') return '';
+  return `/${prefix.replace(/^\/+|\/+$/g, '')}`;
+};
+
+const joinRoutePath = (prefix: string, path: string): string => {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${prefix}${normalizedPath}`;
+};