@sentropic/auth-hono 0.2.1 → 0.3.0

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}`;
+};

package/src/oauth/session-resolver.ts

@@ -0,0 +1,48 @@
+import type {
+  AuthHonoPorts,
+  AuthHonoSessionClaims,
+  AuthHonoSessionRecord,
+  AuthHonoUserRecord,
+} from '../ports.js';
+
+export interface OAuthResolvedSession {
+  claims: AuthHonoSessionClaims;
+  sessionRecord: AuthHonoSessionRecord;
+  user: AuthHonoUserRecord;
+}
+
+export const resolveOAuthSession = async (
+  request: Request,
+  ports: AuthHonoPorts
+): Promise<OAuthResolvedSession | null> => {
+  const token = ports.cookies.readSessionToken(request);
+  if (!token) return null;
+
+  const claims = await ports.tokens.verifySessionToken(token);
+  if (!claims) return null;
+
+  const tokenHash = await ports.tokens.hashSecret(token);
+  const sessionRecord = await ports.sessions.findByTokenHash(tokenHash);
+  const now = ports.clock.now();
+  if (
+    !sessionRecord ||
+    sessionRecord.id !== claims.sessionId ||
+    sessionRecord.userId !== claims.userId ||
+    sessionRecord.revokedAt ||
+    sessionRecord.expiresAt <= now
+  ) {
+    return null;
+  }
+
+  const user = await ports.users.findById(claims.userId);
+  if (!user) return null;
+
+  const decision = await ports.accountPolicy.canAuthenticate(user, now);
+  if (!decision.allowed) return null;
+
+  await ports.sessions.touch(sessionRecord.id, now);
+  return { claims, sessionRecord, user };
+};
+
+export const resolveOAuthAcr = (session: AuthHonoSessionRecord): string =>
+  session.mfaVerified ? 'urn:sentropic:loa:passkey-fresh' : 'urn:sentropic:loa:bearer';

package/src/oauth/state-codec.ts

@@ -0,0 +1,98 @@
+export interface OAuthContinuationState {
+  acr?: string;
+  authTime?: string;
+  clientId: string;
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+  createdAt: string;
+  dpopJkt: string | null;
+  expiresAt: string;
+  nonce: string | null;
+  redirectUri: string;
+  scope: string;
+  state: string | null;
+  tenantId: string | null;
+  userId?: string;
+}
+
+export interface OAuthContinuationCodec {
+  seal(payload: OAuthContinuationState): Promise<string> | string;
+  unseal(token: string): Promise<OAuthContinuationState | null> | OAuthContinuationState | null;
+}
+
+export interface CreateOAuthHmacStateCodecOptions {
+  secret: string;
+}
+
+export const createOAuthHmacStateCodec = ({
+  secret,
+}: CreateOAuthHmacStateCodecOptions): OAuthContinuationCodec => {
+  if (!secret) {
+    throw new Error('OAuth state codec secret is required.');
+  }
+
+  return {
+    async seal(payload) {
+      const body = base64urlEncode(textEncoder.encode(JSON.stringify(payload)));
+      return `${body}.${await sign(body, secret)}`;
+    },
+
+    async unseal(token) {
+      const [body, signature, extra] = token.split('.');
+      if (!body || !signature || extra !== undefined) return null;
+
+      const expected = await sign(body, secret);
+      const actualBytes = base64urlDecode(signature);
+      const expectedBytes = base64urlDecode(expected);
+      if (!timingSafeEqual(actualBytes, expectedBytes)) return null;
+
+      try {
+        return JSON.parse(textDecoder.decode(base64urlDecode(body))) as OAuthContinuationState;
+      } catch {
+        return null;
+      }
+    },
+  };
+};
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+const sign = async (body: string, secret: string): Promise<string> => {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    textEncoder.encode(secret),
+    { hash: 'SHA-256', name: 'HMAC' },
+    false,
+    ['sign']
+  );
+  const signature = await crypto.subtle.sign('HMAC', key, textEncoder.encode(body));
+  return base64urlEncode(new Uint8Array(signature));
+};
+
+const timingSafeEqual = (actual: Uint8Array, expected: Uint8Array): boolean => {
+  if (actual.byteLength !== expected.byteLength) return false;
+  let diff = 0;
+  for (let index = 0; index < actual.byteLength; index += 1) {
+    diff |= actual[index] ^ expected[index];
+  }
+  return diff === 0;
+};
+
+const base64urlEncode = (bytes: Uint8Array): string => {
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+};
+
+const base64urlDecode = (value: string): Uint8Array => {
+  const base64 = value.replaceAll('-', '+').replaceAll('_', '/').padEnd(Math.ceil(value.length / 4) * 4, '=');
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+};

package/src/oauth/state-store-types.ts

@@ -0,0 +1,94 @@
+import type { JWK, KeyLike } from 'jose';
+
+export type OauthTokenType = 'access_token' | 'id_token';
+
+export interface OauthClientRecord {
+  id: string;
+  clientId: string;
+  clientSecretHash: string | null;
+  name: string;
+  redirectUris: string[];
+  allowedScopes: string[];
+  grantTypes: string[];
+  responseTypes: string[];
+  tokenEndpointAuthMethod: 'client_secret_basic' | 'none' | (string & {});
+  dpopBoundAccessTokens: boolean;
+  requirePkce: boolean;
+  tenantId: string | null;
+  ownerUserId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface AuthCodePayload {
+  clientId: string;
+  userId: string;
+  tenantId: string | null;
+  redirectUri: string;
+  scope: string;
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+  dpopJkt: string | null;
+  nonce: string | null;
+  acr: string;
+  authTime: Date;
+  expiresAt: Date;
+  createdAt: Date;
+}
+
+export interface TokenMeta {
+  jti: string;
+  tokenType: OauthTokenType;
+  clientId: string;
+  userId: string;
+  tenantId: string | null;
+  scope: string;
+  audience: string;
+  dpopJkt: string | null;
+  expiresAt: Date;
+  createdAt: Date;
+}
+
+export interface DpopProofRecord {
+  jti: string;
+  expiresAt: Date;
+  createdAt: Date;
+}
+
+export interface OauthStateStorePort {
+  findClient(clientId: string): Promise<OauthClientRecord | null>;
+  saveAuthCode(code: string, payload: AuthCodePayload, ttlSec: number): Promise<void>;
+  consumeAuthCode(code: string): Promise<AuthCodePayload | null>;
+  saveTokenMeta(jti: string, meta: TokenMeta, ttlSec: number): Promise<void>;
+  findTokenMeta(jti: string): Promise<TokenMeta | null>;
+  revokeToken(jti: string): Promise<boolean>;
+  isTokenRevoked(jti: string): Promise<boolean>;
+  recordDpopJti(jti: string, expiresAt: Date): Promise<boolean>;
+  purgeExpired(): Promise<number>;
+}
+
+export type JwksPublicJwk = JWK & {
+  alg?: 'EdDSA' | (string & {});
+  crv: 'Ed25519' | (string & {});
+  kid?: string;
+  kty: 'OKP' | (string & {});
+  use?: 'sig' | (string & {});
+  x: string;
+};
+
+export interface JwksKeyRecord {
+  kid: string;
+  alg: 'EdDSA' | (string & {});
+  crv: 'Ed25519' | (string & {});
+  publicJwk: JwksPublicJwk;
+  privateKey?: KeyLike | Uint8Array;
+  active: boolean;
+  createdAt: Date;
+  rotatedAt: Date | null;
+}
+
+export interface JwksPort {
+  getActiveKey(): Promise<JwksKeyRecord | null>;
+  findKeyByKid(kid: string): Promise<JwksKeyRecord | null>;
+  listPublicKeys(): Promise<JwksKeyRecord[]>;
+}

package/src/oauth/token-handler.ts

@@ -0,0 +1,252 @@
+import type { Context } from 'hono';
+
+import type { AuthHonoPorts, AuthHonoUserRecord } from '../ports.js';
+import { createJwksService } from './jwks-service.js';
+import { oauthJsonError } from './http-utils.js';
+import { sha256Base64url } from './crypto-utils.js';
+import { OAuthDpopProofError, verifyOAuthDpopProof } from './dpop.js';
+import type { AuthCodePayload, OauthClientRecord, TokenMeta } from './state-store-types.js';
+
+export interface OAuthTokenHandlerOptions {
+  accessTokenTtlSeconds?: number;
+  dpopIatSkewSeconds?: number;
+  idTokenTtlSeconds?: number;
+  issuer: string;
+  ports: AuthHonoPorts;
+}
+
+interface ClientAuthentication {
+  client: OauthClientRecord;
+  secret?: string;
+}
+
+export const createOAuthTokenHandler =
+  (options: OAuthTokenHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const form = new URLSearchParams(await c.req.text());
+    if (form.get('grant_type') !== 'authorization_code') {
+      return oauthJsonError(c, 400, 'unsupported_grant_type', 'Only authorization_code grant is supported.');
+    }
+
+    const auth = await authenticateClient(c, form, options.ports);
+    if (auth instanceof Response) return auth;
+
+    const codePayload = await options.ports.oauthStateStore.consumeAuthCode(form.get('code') ?? '');
+    if (!codePayload || codePayload.clientId !== auth.client.clientId) {
+      return oauthJsonError(c, 400, 'invalid_grant', 'Authorization code is invalid or already used.');
+    }
+    if (form.get('redirect_uri') !== codePayload.redirectUri) {
+      return oauthJsonError(c, 400, 'invalid_grant', 'redirect_uri does not match the authorization request.');
+    }
+    if ((await sha256Base64url(form.get('code_verifier') ?? '')) !== codePayload.codeChallenge) {
+      return oauthJsonError(c, 400, 'invalid_grant', 'PKCE verification failed.');
+    }
+
+    const dpopJkt = await resolveDpopJkt(c, options, auth.client, codePayload);
+    if (dpopJkt instanceof Response) return dpopJkt;
+
+    const user = await options.ports.users.findById(codePayload.userId);
+    if (!user) return oauthJsonError(c, 400, 'invalid_grant', 'Authorization code user is invalid.');
+
+    const tokens = await issueTokens(options, auth.client, codePayload, user, dpopJkt);
+    return c.json(tokens);
+  };
+
+const authenticateClient = async (
+  c: Context,
+  form: URLSearchParams,
+  ports: AuthHonoPorts
+): Promise<ClientAuthentication | Response> => {
+  const credentials = parseClientCredentials(c.req.header('authorization'), form);
+  if (!credentials.clientId) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client authentication is required.');
+  }
+
+  const client = await ports.oauthStateStore.findClient(credentials.clientId);
+  if (!client) return oauthJsonError(c, 401, 'invalid_client', 'Client authentication failed.');
+
+  if (client.tokenEndpointAuthMethod === 'none') {
+    return { client };
+  }
+
+  if (!credentials.secret || !client.clientSecretHash) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client secret is required.');
+  }
+
+  const secretHash = await ports.tokens.hashSecret(credentials.secret);
+  if (secretHash !== client.clientSecretHash) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client authentication failed.');
+  }
+
+  return { client, secret: credentials.secret };
+};
+
+const parseClientCredentials = (
+  authorization: string | undefined,
+  form: URLSearchParams
+): { clientId: string | null; secret?: string } => {
+  if (authorization?.startsWith('Basic ')) {
+    const decoded = atob(authorization.slice('Basic '.length));
+    const separator = decoded.indexOf(':');
+    return {
+      clientId: separator >= 0 ? decoded.slice(0, separator) : decoded,
+      secret: separator >= 0 ? decoded.slice(separator + 1) : '',
+    };
+  }
+
+  return {
+    clientId: form.get('client_id'),
+    secret: form.get('client_secret') ?? undefined,
+  };
+};
+
+const resolveDpopJkt = async (
+  c: Context,
+  options: OAuthTokenHandlerOptions,
+  client: OauthClientRecord,
+  codePayload: AuthCodePayload
+): Promise<string | null | Response> => {
+  if (!client.dpopBoundAccessTokens) return null;
+
+  const proof = c.req.header('dpop');
+  if (!proof) return oauthJsonError(c, 400, 'invalid_dpop_proof', 'DPoP proof is required.');
+
+  try {
+    const verified = await verifyOAuthDpopProof({
+      htm: 'POST',
+      htu: c.req.url,
+      iatSkewSeconds: options.dpopIatSkewSeconds,
+      ports: options.ports,
+      proof,
+    });
+    if (codePayload.dpopJkt && codePayload.dpopJkt !== verified.jkt) {
+      return oauthJsonError(c, 400, 'invalid_grant', 'DPoP key does not match the authorization code.');
+    }
+    return verified.jkt;
+  } catch (error) {
+    if (error instanceof OAuthDpopProofError) {
+      return oauthJsonError(c, 400, 'invalid_dpop_proof', error.message);
+    }
+    throw error;
+  }
+};
+
+const issueTokens = async (
+  options: OAuthTokenHandlerOptions,
+  client: OauthClientRecord,
+  codePayload: AuthCodePayload,
+  user: AuthHonoUserRecord,
+  dpopJkt: string | null
+) => {
+  const accessTokenTtlSeconds = options.accessTokenTtlSeconds ?? 3600;
+  const idTokenTtlSeconds = options.idTokenTtlSeconds ?? 3600;
+  const now = options.ports.clock.now();
+  const accessExpiresAt = options.ports.clock.addSeconds(now, accessTokenTtlSeconds);
+  const idExpiresAt = options.ports.clock.addSeconds(now, idTokenTtlSeconds);
+  const scopes = codePayload.scope.split(/\s+/).filter(Boolean);
+  const cnf = dpopJkt ? { jkt: dpopJkt } : undefined;
+  const jwks = createJwksService({ clock: options.ports.clock, jwksPort: options.ports.jwks });
+  const accessJti = options.ports.random.uuid();
+  const accessAudience = `${trimTrailingSlash(options.issuer)}/api/v1/auth/oauth/userinfo`;
+  const accessToken = await jwks.signJwt(
+    {
+      acr: codePayload.acr,
+      auth_time: toEpochSeconds(codePayload.authTime),
+      client_id: client.clientId,
+      ...(cnf ? { cnf } : {}),
+      scope: codePayload.scope,
+    },
+    {
+      audience: accessAudience,
+      expiresAt: accessExpiresAt,
+      issuer: trimTrailingSlash(options.issuer),
+      jti: accessJti,
+      subject: codePayload.userId,
+      type: 'JWT',
+    }
+  );
+
+  await options.ports.oauthStateStore.saveTokenMeta(
+    accessJti,
+    tokenMeta({
+      audience: accessAudience,
+      client,
+      codePayload,
+      dpopJkt,
+      expiresAt: accessExpiresAt,
+      jti: accessJti,
+      tokenType: 'access_token',
+    }),
+    accessTokenTtlSeconds
+  );
+
+  const response: Record<string, unknown> = {
+    access_token: accessToken,
+    expires_in: accessTokenTtlSeconds,
+    scope: codePayload.scope,
+    token_type: dpopJkt ? 'DPoP' : 'Bearer',
+  };
+
+  if (scopes.includes('openid')) {
+    const idJti = options.ports.random.uuid();
+    const idToken = await jwks.signJwt(
+      {
+        acr: codePayload.acr,
+        auth_time: toEpochSeconds(codePayload.authTime),
+        ...(cnf ? { cnf } : {}),
+        ...(scopes.includes('email') ? { email: user.email, email_verified: user.emailVerified } : {}),
+        ...(scopes.includes('profile') ? { name: user.displayName } : {}),
+        ...(codePayload.nonce ? { nonce: codePayload.nonce } : {}),
+      },
+      {
+        audience: client.clientId,
+        expiresAt: idExpiresAt,
+        issuer: trimTrailingSlash(options.issuer),
+        jti: idJti,
+        subject: codePayload.userId,
+        type: 'JWT',
+      }
+    );
+    response.id_token = idToken;
+    await options.ports.oauthStateStore.saveTokenMeta(
+      idJti,
+      tokenMeta({
+        audience: client.clientId,
+        client,
+        codePayload,
+        dpopJkt,
+        expiresAt: idExpiresAt,
+        jti: idJti,
+        tokenType: 'id_token',
+      }),
+      idTokenTtlSeconds
+    );
+  }
+
+  return response;
+};
+
+const tokenMeta = (input: {
+  audience: string;
+  client: OauthClientRecord;
+  codePayload: AuthCodePayload;
+  dpopJkt: string | null;
+  expiresAt: Date;
+  jti: string;
+  tokenType: 'access_token' | 'id_token';
+}): TokenMeta => ({
+  audience: input.audience,
+  clientId: input.client.clientId,
+  createdAt: input.codePayload.createdAt,
+  dpopJkt: input.dpopJkt,
+  expiresAt: input.expiresAt,
+  jti: input.jti,
+  scope: input.codePayload.scope,
+  tenantId: input.codePayload.tenantId,
+  tokenType: input.tokenType,
+  userId: input.codePayload.userId,
+});
+
+const toEpochSeconds = (date: Date): number => Math.floor(date.getTime() / 1000);
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/u, '');