@sentropic/auth-hono 0.2.1 → 0.4.0

package/src/oauth/token-handler.ts

@@ -0,0 +1,423 @@
+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, ServiceClientRecord, TokenMeta } from './state-store-types.js';
+
+const DEFAULT_SERVICE_ACCESS_TOKEN_TTL_SECONDS = 900;
+
+export interface OAuthTokenHandlerOptions {
+  accessTokenTtlSeconds?: number;
+  dpopIatSkewSeconds?: number;
+  idTokenTtlSeconds?: number;
+  issuer: string;
+  ports: AuthHonoPorts;
+  serviceAccessTokenTtlSeconds?: number;
+}
+
+interface ClientAuthentication {
+  client: OauthClientRecord;
+  secret?: string;
+}
+
+interface ServiceClientAuthentication {
+  client: ServiceClientRecord;
+  secret: string;
+}
+
+export const createOAuthTokenHandler =
+  (options: OAuthTokenHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const form = new URLSearchParams(await c.req.text());
+    const grantType = form.get('grant_type');
+    if (grantType === 'client_credentials') {
+      return handleClientCredentials(c, form, options);
+    }
+    if (grantType !== 'authorization_code') {
+      return oauthJsonError(
+        c,
+        400,
+        'unsupported_grant_type',
+        'Only authorization_code and client_credentials grants are 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 handleClientCredentials = async (
+  c: Context,
+  form: URLSearchParams,
+  options: OAuthTokenHandlerOptions
+): Promise<Response> => {
+  const findServiceClient = options.ports.oauthStateStore.findServiceClient;
+  if (!findServiceClient) {
+    return oauthJsonError(c, 400, 'unsupported_grant_type', 'The client_credentials grant is not supported.');
+  }
+
+  const auth = await authenticateServiceClient(c, form, options.ports, findServiceClient);
+  if (auth instanceof Response) return auth;
+
+  const scope = resolveServiceScope(c, form, auth.client);
+  if (scope instanceof Response) return scope;
+
+  const resource = resolveResourceIndicator(c, form, auth.client);
+  if (resource instanceof Response) return resource;
+
+  const dpopJkt = await resolveServiceDpopJkt(c, options, auth.client);
+  if (dpopJkt instanceof Response) return dpopJkt;
+
+  const tokens = await issueServiceToken(options, auth.client, scope, resource, dpopJkt);
+  return c.json(tokens);
+};
+
+const authenticateServiceClient = async (
+  c: Context,
+  form: URLSearchParams,
+  ports: AuthHonoPorts,
+  findServiceClient: NonNullable<AuthHonoPorts['oauthStateStore']['findServiceClient']>
+): Promise<ServiceClientAuthentication | Response> => {
+  const credentials = parseClientCredentials(c.req.header('authorization'), form);
+  if (!credentials.clientId || !credentials.secret) {
+    return oauthJsonError(c, 401, 'invalid_client', 'Client authentication is required.');
+  }
+
+  const client = await findServiceClient(credentials.clientId);
+  if (!client) return oauthJsonError(c, 401, 'invalid_client', 'Client authentication failed.');
+
+  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 resolveServiceScope = (
+  c: Context,
+  form: URLSearchParams,
+  client: ServiceClientRecord
+): string | Response => {
+  const requested = (form.get('scope') ?? '').split(/\s+/).filter(Boolean);
+  if (requested.length === 0) {
+    return client.allowedScopes.join(' ');
+  }
+  const allowed = new Set(client.allowedScopes);
+  const unauthorized = requested.filter((scope) => !allowed.has(scope));
+  if (unauthorized.length > 0) {
+    return oauthJsonError(c, 400, 'invalid_scope', `Scope not allowed: ${unauthorized.join(' ')}.`);
+  }
+  return requested.join(' ');
+};
+
+const resolveResourceIndicator = (
+  c: Context,
+  form: URLSearchParams,
+  client: ServiceClientRecord
+): string | Response => {
+  const requested = form.get('resource');
+  const indicators = client.resourceIndicators;
+
+  if (requested) {
+    if (!indicators.includes(requested)) {
+      return oauthJsonError(c, 400, 'invalid_target', 'Requested resource is not allowed for this client.');
+    }
+    return requested;
+  }
+
+  if (indicators.length === 1) {
+    return indicators[0];
+  }
+  if (indicators.length === 0) {
+    return oauthJsonError(c, 400, 'invalid_target', 'A resource indicator is required for this client.');
+  }
+  return oauthJsonError(c, 400, 'invalid_target', 'A resource indicator must be specified when multiple are allowed.');
+};
+
+const resolveServiceDpopJkt = async (
+  c: Context,
+  options: OAuthTokenHandlerOptions,
+  client: ServiceClientRecord
+): 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,
+    });
+    return verified.jkt;
+  } catch (error) {
+    if (error instanceof OAuthDpopProofError) {
+      return oauthJsonError(c, 400, 'invalid_dpop_proof', error.message);
+    }
+    throw error;
+  }
+};
+
+const issueServiceToken = async (
+  options: OAuthTokenHandlerOptions,
+  client: ServiceClientRecord,
+  scope: string,
+  resource: string,
+  dpopJkt: string | null
+) => {
+  const ttlSeconds = options.serviceAccessTokenTtlSeconds ?? DEFAULT_SERVICE_ACCESS_TOKEN_TTL_SECONDS;
+  const now = options.ports.clock.now();
+  const expiresAt = options.ports.clock.addSeconds(now, ttlSeconds);
+  const cnf = dpopJkt ? { jkt: dpopJkt } : undefined;
+  const jwks = createJwksService({ clock: options.ports.clock, jwksPort: options.ports.jwks });
+  const accessJti = options.ports.random.uuid();
+  const accessToken = await jwks.signJwt(
+    {
+      client_id: client.clientId,
+      ...(cnf ? { cnf } : {}),
+      scope,
+    },
+    {
+      audience: resource,
+      expiresAt,
+      issuer: trimTrailingSlash(options.issuer),
+      jti: accessJti,
+      subject: client.clientId,
+      type: 'JWT',
+    }
+  );
+
+  // Service tokens are stateless (BR39d-D5): no saveTokenMeta, no oauth_tokens row.
+  return {
+    access_token: accessToken,
+    expires_in: ttlSeconds,
+    scope,
+    token_type: dpopJkt ? 'DPoP' : 'Bearer',
+  };
+};
+
+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, '');

package/src/oauth/userinfo-handler.ts

@@ -0,0 +1,129 @@
+import type { Context } from 'hono';
+import type { JWTPayload } from 'jose';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { OAuthDpopProofError, verifyOAuthDpopProof } from './dpop.js';
+import { oauthJsonError } from './http-utils.js';
+import { createJwksService } from './jwks-service.js';
+import type { TokenMeta } from './state-store-types.js';
+
+export interface OAuthUserInfoHandlerOptions {
+  dpopIatSkewSeconds?: number;
+  issuer: string;
+  ports: AuthHonoPorts;
+}
+
+export const createOAuthUserInfoHandler =
+  (options: OAuthUserInfoHandlerOptions) =>
+  async (c: Context): Promise<Response> => {
+    const authorization = parseAccessToken(c.req.header('authorization'));
+    if (!authorization) return unauthorized(c, 'Access token is required.');
+
+    const payload = await verifyAccessToken(c, options, authorization.token);
+    if (payload instanceof Response) return payload;
+
+    const meta = await resolveActiveTokenMeta(c, options.ports, payload);
+    if (meta instanceof Response) return meta;
+    if (meta.dpopJkt) {
+      const dpop = await verifyBoundDpop(c, options, authorization, meta);
+      if (dpop instanceof Response) return dpop;
+    }
+
+    const scopes = meta.scope.split(/\s+/).filter(Boolean);
+    if (scopes.some((scope) => !['openid', 'profile', 'email'].includes(scope))) {
+      return unauthorized(c, 'Access token contains unsupported scopes.');
+    }
+
+    const user = await options.ports.users.findById(meta.userId);
+    if (!user) return unauthorized(c, 'Access token user is invalid.');
+
+    return c.json({
+      sub: user.id,
+      ...(scopes.includes('profile') ? { name: user.displayName } : {}),
+      ...(scopes.includes('email') ? { email: user.email, email_verified: user.emailVerified } : {}),
+    });
+  };
+
+const verifyAccessToken = async (
+  c: Context,
+  options: OAuthUserInfoHandlerOptions,
+  token: string
+): Promise<JWTPayload | Response> => {
+  try {
+    const jwks = createJwksService({ clock: options.ports.clock, jwksPort: options.ports.jwks });
+    const result = await jwks.verifyJwt(token, {
+      audience: `${trimTrailingSlash(options.issuer)}/api/v1/auth/oauth/userinfo`,
+      currentDate: options.ports.clock.now(),
+      issuer: trimTrailingSlash(options.issuer),
+    });
+    return result.payload;
+  } catch {
+    return unauthorized(c, 'Access token is invalid.');
+  }
+};
+
+const resolveActiveTokenMeta = async (
+  c: Context,
+  ports: AuthHonoPorts,
+  payload: JWTPayload
+): Promise<TokenMeta | Response> => {
+  const jti = payload.jti;
+  if (!jti) return unauthorized(c, 'Access token jti is missing.');
+
+  const meta = await ports.oauthStateStore.findTokenMeta(jti);
+  if (
+    !meta ||
+    meta.tokenType !== 'access_token' ||
+    meta.expiresAt <= ports.clock.now() ||
+    (await ports.oauthStateStore.isTokenRevoked(jti))
+  ) {
+    return unauthorized(c, 'Access token is inactive.');
+  }
+
+  return meta;
+};
+
+const verifyBoundDpop = async (
+  c: Context,
+  options: OAuthUserInfoHandlerOptions,
+  authorization: { scheme: 'Bearer' | 'DPoP'; token: string },
+  meta: TokenMeta
+): Promise<null | Response> => {
+  const proof = c.req.header('dpop');
+  if (authorization.scheme !== 'DPoP' || !proof) {
+    return unauthorized(c, 'DPoP proof is required for this access token.');
+  }
+
+  try {
+    const verified = await verifyOAuthDpopProof({
+      accessToken: authorization.token,
+      htm: c.req.method,
+      htu: c.req.url,
+      iatSkewSeconds: options.dpopIatSkewSeconds,
+      ports: options.ports,
+      proof,
+    });
+    if (verified.jkt !== meta.dpopJkt) {
+      return unauthorized(c, 'DPoP proof key does not match the access token.');
+    }
+    return null;
+  } catch (error) {
+    if (error instanceof OAuthDpopProofError) {
+      return unauthorized(c, error.message);
+    }
+    throw error;
+  }
+};
+
+const parseAccessToken = (
+  authorization: string | undefined
+): { scheme: 'Bearer' | 'DPoP'; token: string } | null => {
+  const [scheme, token, extra] = authorization?.split(/\s+/) ?? [];
+  if (extra || !token || (scheme !== 'Bearer' && scheme !== 'DPoP')) return null;
+  return { scheme, token };
+};
+
+const unauthorized = (c: Context, message: string): Response =>
+  oauthJsonError(c, 401, 'invalid_token', message);
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/u, '');

package/src/oauth/wellknown-handler.ts

@@ -0,0 +1,52 @@
+import { Hono } from 'hono';
+
+import type { AuthHonoPorts } from '../ports.js';
+import { createJwksService } from './jwks-service.js';
+
+export interface CreateWellKnownRouterOptions {
+  issuer: string;
+  oauthPathPrefix?: string;
+  ports: AuthHonoPorts;
+}
+
+export const createWellKnownRouter = (options: CreateWellKnownRouterOptions): Hono => {
+  const router = new Hono();
+  const issuer = trimTrailingSlash(options.issuer);
+  const oauthPrefix = normalizePathPrefix(options.oauthPathPrefix ?? '/api/v1/auth/oauth');
+
+  router.get('/openid-configuration', (c) =>
+    c.json({
+      authorization_endpoint: `${issuer}${oauthPrefix}/authorize`,
+      claims_supported: ['sub', 'aud', 'iss', 'exp', 'iat', 'nonce', 'auth_time', 'acr', 'email', 'email_verified', 'name'],
+      code_challenge_methods_supported: ['S256'],
+      dpop_signing_alg_values_supported: ['EdDSA'],
+      grant_types_supported: ['authorization_code', 'client_credentials'],
+      id_token_signing_alg_values_supported: ['EdDSA'],
+      introspection_endpoint: `${issuer}${oauthPrefix}/introspect`,
+      issuer,
+      jwks_uri: `${issuer}/.well-known/jwks.json`,
+      response_types_supported: ['code'],
+      revocation_endpoint: `${issuer}${oauthPrefix}/revoke`,
+      scopes_supported: ['openid', 'profile', 'email'],
+      subject_types_supported: ['public'],
+      token_endpoint: `${issuer}${oauthPrefix}/token`,
+      token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],
+      userinfo_endpoint: `${issuer}${oauthPrefix}/userinfo`,
+    })
+  );
+
+  router.get('/jwks.json', async (c) => {
+    const jwks = createJwksService({ clock: options.ports.clock, jwksPort: options.ports.jwks });
+    c.header('Cache-Control', 'public, max-age=300');
+    return c.json(await jwks.getPublicJwks());
+  });
+
+  return router;
+};
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/u, '');
+
+const normalizePathPrefix = (value: string): string => {
+  const trimmed = value.replace(/^\/+|\/+$/gu, '');
+  return trimmed ? `/${trimmed}` : '';
+};

package/src/ports.ts

@@ -1,3 +1,18 @@
+import type { JwksPort, OauthStateStorePort } from './oauth/state-store-types.js';
+
+export type {
+  AuthCodePayload,
+  DpopProofRecord,
+  JwksKeyRecord,
+  JwksPort,
+  JwksPublicJwk,
+  OauthClientRecord,
+  OauthStateStorePort,
+  OauthTokenType,
+  ServiceClientRecord,
+  TokenMeta,
+} from './oauth/state-store-types.js';
+
 export type AuthHonoAccountStatus =
   | 'active'
   | 'pending_admin_approval'
@@ -286,4 +301,6 @@ export interface AuthHonoPorts {
   clock: AuthHonoClockPort;
   random: AuthHonoRandomPort;
   accountPolicy: AuthHonoAccountPolicyPort;
+  oauthStateStore: OauthStateStorePort;
+  jwks: JwksPort;
 }