@sentropic/auth-hono 0.2.1 → 0.3.0

package/src/oauth/authorize-handler.ts

@@ -0,0 +1,201 @@
+import type { Context } from 'hono';
+
+import type { AuthHonoPorts } from '../ports.js';
+import type { OauthClientRecord } from './state-store-types.js';
+import type { OAuthContinuationCodec, OAuthContinuationState } from './state-codec.js';
+import { appendParams, oauthJsonError, redirectWithOAuthError } from './http-utils.js';
+import { resolveOAuthAcr, resolveOAuthSession } from './session-resolver.js';
+
+export interface OAuthAuthorizeHandlerOptions {
+  consentUrl: string;
+  issuer: string;
+  loginUrl: string;
+  ports: AuthHonoPorts;
+  stateCodec: OAuthContinuationCodec;
+  stateTtlSeconds?: number;
+}
+
+interface ValidatedAuthorizeRequest {
+  client: OauthClientRecord;
+  codeChallenge: string;
+  dpopJkt: string | null;
+  nonce: string | null;
+  redirectUri: string;
+  scope: string;
+  state: string | null;
+}
+
+export const createOAuthAuthorizeHandler =
+  (options: OAuthAuthorizeHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const continuation = c.req.query('continue');
+    if (continuation) {
+      return resumeLoginContinuation(c, options, continuation);
+    }
+
+    const validation = await validateAuthorizeRequest(c, options.ports);
+    if (validation instanceof Response) return validation;
+
+    const prompt = c.req.query('prompt') ?? '';
+    const session = await resolveOAuthSession(c.req.raw, options.ports);
+
+    if (!session || prompt === 'login') {
+      if (prompt === 'none') {
+        return redirectWithOAuthError(validation.redirectUri, 'login_required', validation.state, c.req.url);
+      }
+
+      const continuation = await sealContinuation(c, options, validation);
+      return c.redirect(appendParams(options.loginUrl, { continue: continuation }, c.req.url), 302);
+    }
+
+    if (prompt === 'none') {
+      return redirectWithOAuthError(validation.redirectUri, 'consent_required', validation.state, c.req.url);
+    }
+
+    const sealedState = await sealContinuation(c, options, validation, {
+      acr: resolveOAuthAcr(session.sessionRecord),
+      authTime: session.sessionRecord.createdAt.toISOString(),
+      userId: session.user.id,
+    });
+
+    return c.redirect(appendParams(options.consentUrl, { state: sealedState }, c.req.url), 302);
+  };
+
+const resumeLoginContinuation = async (
+  c: Context,
+  options: OAuthAuthorizeHandlerOptions,
+  continuation: string
+): Promise<Response> => {
+  const payload = await options.stateCodec.unseal(continuation);
+  const now = options.ports.clock.now();
+  if (!payload || payload.userId || payload.codeChallengeMethod !== 'S256' || new Date(payload.expiresAt) <= now) {
+    return oauthJsonError(c, 400, 'invalid_request', 'OAuth continuation is invalid or expired.');
+  }
+
+  const client = await options.ports.oauthStateStore.findClient(payload.clientId);
+  if (!client) return oauthJsonError(c, 400, 'invalid_request', 'Unknown OAuth client.');
+
+  const redirectError = validateRedirectUri(client, payload.redirectUri);
+  if (redirectError) return oauthJsonError(c, 400, 'invalid_request', redirectError);
+
+  const scopeResult = validateScope(payload.scope, client, payload.redirectUri, payload.state, c.req.url);
+  if (scopeResult instanceof Response) return scopeResult;
+
+  const session = await resolveOAuthSession(c.req.raw, options.ports);
+  if (!session) {
+    return c.redirect(appendParams(options.loginUrl, { continue: continuation }, c.req.url), 302);
+  }
+
+  const expiresAt = options.ports.clock.addSeconds(now, options.stateTtlSeconds ?? 10 * 60);
+  const sealedState = await options.stateCodec.seal({
+    ...payload,
+    acr: resolveOAuthAcr(session.sessionRecord),
+    authTime: session.sessionRecord.createdAt.toISOString(),
+    createdAt: now.toISOString(),
+    expiresAt: expiresAt.toISOString(),
+    scope: scopeResult,
+    userId: session.user.id,
+  });
+
+  return c.redirect(appendParams(options.consentUrl, { state: sealedState }, c.req.url), 302);
+};
+
+const validateAuthorizeRequest = async (
+  c: Context,
+  ports: AuthHonoPorts
+): Promise<ValidatedAuthorizeRequest | Response> => {
+  const clientId = c.req.query('client_id');
+  const client = clientId ? await ports.oauthStateStore.findClient(clientId) : null;
+  if (!client) {
+    return oauthJsonError(c, 400, 'invalid_request', 'Unknown OAuth client.');
+  }
+
+  const redirectUri = c.req.query('redirect_uri') ?? '';
+  const redirectError = validateRedirectUri(client, redirectUri);
+  if (redirectError) {
+    return oauthJsonError(c, 400, 'invalid_request', redirectError);
+  }
+
+  const state = c.req.query('state') ?? null;
+  if (c.req.query('response_type') !== 'code') {
+    return redirectWithOAuthError(redirectUri, 'unsupported_response_type', state, c.req.url);
+  }
+
+  const codeChallenge = c.req.query('code_challenge') ?? '';
+  if (!codeChallenge || c.req.query('code_challenge_method') !== 'S256') {
+    return redirectWithOAuthError(redirectUri, 'invalid_request', state, c.req.url);
+  }
+
+  const scopeResult = validateScope(c.req.query('scope') ?? '', client, redirectUri, state, c.req.url);
+  if (scopeResult instanceof Response) return scopeResult;
+
+  return {
+    client,
+    codeChallenge,
+    dpopJkt: c.req.query('dpop_jkt') ?? null,
+    nonce: c.req.query('nonce') ?? null,
+    redirectUri,
+    scope: scopeResult,
+    state,
+  };
+};
+
+const validateRedirectUri = (client: OauthClientRecord, redirectUri: string): string | null => {
+  if (!client.redirectUris.includes(redirectUri)) return 'redirect_uri is not registered for this client.';
+
+  let parsed: URL;
+  try {
+    parsed = new URL(redirectUri);
+  } catch {
+    return 'redirect_uri must be an absolute URI.';
+  }
+
+  if (parsed.hash) return 'redirect_uri must not contain a fragment.';
+  if (parsed.username || parsed.password) return 'redirect_uri must not contain credentials.';
+  if (parsed.protocol === 'https:') return null;
+  if (parsed.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(parsed.hostname)) return null;
+  return 'redirect_uri must use https except for localhost development callbacks.';
+};
+
+const validateScope = (
+  scope: string,
+  client: OauthClientRecord,
+  redirectUri: string,
+  state: string | null,
+  baseUrl: string
+): string | Response => {
+  const requestedScopes = scope.split(/\s+/).filter(Boolean);
+  if (requestedScopes.includes('offline_access')) {
+    return redirectWithOAuthError(redirectUri, 'invalid_scope', state, baseUrl);
+  }
+  if (requestedScopes.some((requestedScope) => !client.allowedScopes.includes(requestedScope))) {
+    return redirectWithOAuthError(redirectUri, 'invalid_scope', state, baseUrl);
+  }
+  return requestedScopes.join(' ');
+};
+
+const sealContinuation = async (
+  c: Context,
+  options: OAuthAuthorizeHandlerOptions,
+  request: ValidatedAuthorizeRequest,
+  session?: Pick<OAuthContinuationState, 'acr' | 'authTime' | 'userId'>
+): Promise<string> => {
+  const now = options.ports.clock.now();
+  const expiresAt = options.ports.clock.addSeconds(now, options.stateTtlSeconds ?? 10 * 60);
+  return options.stateCodec.seal({
+    acr: session?.acr,
+    authTime: session?.authTime,
+    clientId: request.client.clientId,
+    codeChallenge: request.codeChallenge,
+    codeChallengeMethod: 'S256',
+    createdAt: now.toISOString(),
+    dpopJkt: request.dpopJkt,
+    expiresAt: expiresAt.toISOString(),
+    nonce: request.nonce,
+    redirectUri: request.redirectUri,
+    scope: request.scope,
+    state: request.state,
+    tenantId: request.client.tenantId,
+    userId: session?.userId,
+  });
+};

package/src/oauth/consent-decision-handler.ts

@@ -0,0 +1,93 @@
+import type { Context } from 'hono';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { appendParams, oauthJsonError, redirectOrJson } from './http-utils.js';
+import type { OAuthContinuationCodec, OAuthContinuationState } from './state-codec.js';
+import { resolveOAuthSession } from './session-resolver.js';
+
+export interface OAuthConsentHandlerOptions {
+  authorizationCodeTtlSeconds?: number;
+  ports: AuthHonoPorts;
+  stateCodec: OAuthContinuationCodec;
+}
+
+export const createOAuthConsentDetailsHandler =
+  (options: OAuthConsentHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const state = c.req.query('state') ?? '';
+    const payload = await validateConsentState(c, options, state);
+    if (payload instanceof Response) return payload;
+
+    const client = await options.ports.oauthStateStore.findClient(payload.clientId);
+    if (!client) return oauthJsonError(c, 400, 'invalid_request', 'Unknown OAuth client.');
+
+    return c.json({
+      clientName: client.name,
+      redirectUri: payload.redirectUri,
+      scopes: payload.scope.split(/\s+/).filter(Boolean),
+    });
+  };
+
+export const createOAuthConsentDecisionHandler =
+  (options: OAuthConsentHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const body = await c.req.json<{ decision?: string; state?: string }>().catch(() => null);
+    if (!body?.state || !['approve', 'deny'].includes(body.decision ?? '')) {
+      return oauthJsonError(c, 400, 'invalid_request', 'Consent decision and state are required.');
+    }
+
+    const payload = await validateConsentState(c, options, body.state);
+    if (payload instanceof Response) return payload;
+
+    if (body.decision === 'deny') {
+      return redirectOrJson(
+        c,
+        appendParams(payload.redirectUri, { error: 'access_denied', state: payload.state }, c.req.url)
+      );
+    }
+
+    const code = options.ports.random.token(32);
+    const now = options.ports.clock.now();
+    await options.ports.oauthStateStore.saveAuthCode(
+      code,
+      {
+        acr: payload.acr ?? 'urn:sentropic:loa:bearer',
+        authTime: new Date(payload.authTime ?? now.toISOString()),
+        clientId: payload.clientId,
+        codeChallenge: payload.codeChallenge,
+        codeChallengeMethod: 'S256',
+        createdAt: now,
+        dpopJkt: payload.dpopJkt,
+        expiresAt: options.ports.clock.addSeconds(now, options.authorizationCodeTtlSeconds ?? 60),
+        nonce: payload.nonce,
+        redirectUri: payload.redirectUri,
+        scope: payload.scope,
+        tenantId: payload.tenantId,
+        userId: payload.userId ?? '',
+      },
+      options.authorizationCodeTtlSeconds ?? 60
+    );
+
+    return redirectOrJson(
+      c,
+      appendParams(payload.redirectUri, { code, state: payload.state }, c.req.url)
+    );
+  };
+
+const validateConsentState = async (
+  c: Context,
+  options: OAuthConsentHandlerOptions,
+  sealedState: string
+): Promise<OAuthContinuationState | Response> => {
+  const payload = await options.stateCodec.unseal(sealedState);
+  if (!payload || !payload.userId || new Date(payload.expiresAt) <= options.ports.clock.now()) {
+    return oauthJsonError(c, 400, 'invalid_request', 'OAuth consent state is invalid or expired.');
+  }
+
+  const session = await resolveOAuthSession(c.req.raw, options.ports);
+  if (!session || session.user.id !== payload.userId) {
+    return oauthJsonError(c, 401, 'login_required', 'A valid user session is required.');
+  }
+
+  return payload;
+};

package/src/oauth/crypto-utils.ts

@@ -0,0 +1,14 @@
+const textEncoder = new TextEncoder();
+
+export const sha256Base64url = async (value: string): Promise<string> => {
+  const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(value));
+  return base64urlEncode(new Uint8Array(digest));
+};
+
+export const base64urlEncode = (bytes: Uint8Array): string => {
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+};

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);