@sentropic/auth-hono 0.2.1 → 0.4.0

package/src/oauth/service-auth-middleware.ts

@@ -0,0 +1,250 @@
+import {
+  calculateJwkThumbprint,
+  decodeProtectedHeader,
+  importJWK,
+  jwtVerify,
+  type JWK,
+  type JWTPayload,
+} from 'jose';
+import type { Context, MiddlewareHandler } from 'hono';
+
+import type { AuthHonoClockPort } from '../ports.js';
+import { sha256Base64url } from './crypto-utils.js';
+import type { JwksPort, OauthStateStorePort } from './state-store-types.js';
+
+/**
+ * Narrow port set for resource-server verification (BR39d-D6). Resource servers
+ * must not construct users/credentials/sessions/email ports just to verify a
+ * bearer or DPoP-bound access token.
+ */
+export interface ServiceAuthPorts {
+  clock: AuthHonoClockPort;
+  jwks: JwksPort;
+  dpopReplay?: Pick<OauthStateStorePort, 'recordDpopJti'>;
+}
+
+export interface ServiceAuthContext {
+  clientId: string;
+  scopes: string[];
+  jkt: string | null;
+}
+
+export interface CreateRequireServiceAuthOptions {
+  issuer: string;
+  requiredScopes?: string[];
+  resource: string;
+  ports: ServiceAuthPorts;
+  /** DPoP proof iat acceptance window in seconds (default 60). */
+  dpopIatSkewSeconds?: number;
+  /** Context key the verified service-client context is stored under (default 'serviceClient'). */
+  contextKey?: string;
+}
+
+class ServiceAuthError extends Error {
+  constructor(
+    readonly status: 401 | 403,
+    readonly code: string,
+    message: string,
+    readonly scheme: 'Bearer' | 'DPoP' = 'Bearer'
+  ) {
+    super(message);
+    this.name = 'ServiceAuthError';
+  }
+}
+
+export const createRequireServiceAuth = (
+  options: CreateRequireServiceAuthOptions
+): MiddlewareHandler => {
+  const issuer = trimTrailingSlash(options.issuer);
+  const requiredScopes = options.requiredScopes ?? [];
+  const contextKey = options.contextKey ?? 'serviceClient';
+
+  return async (c, next) => {
+    try {
+      const { scheme, token } = parseAuthorization(c.req.header('authorization'));
+      const payload = await verifyAccessToken(token, options.ports, issuer, options.resource);
+      const scopes = parseScopes(payload.scope);
+      assertScopes(scopes, requiredScopes);
+
+      const jkt = await enforceDpop(c, payload, token, scheme, options);
+
+      const serviceContext: ServiceAuthContext = {
+        clientId: typeof payload.client_id === 'string' ? payload.client_id : String(payload.sub ?? ''),
+        jkt,
+        scopes,
+      };
+      c.set(contextKey, serviceContext);
+
+      await next();
+    } catch (error) {
+      if (error instanceof ServiceAuthError) {
+        return serviceAuthErrorResponse(c, error);
+      }
+      throw error;
+    }
+  };
+};
+
+const parseAuthorization = (header: string | undefined): { scheme: 'Bearer' | 'DPoP'; token: string } => {
+  if (!header) {
+    throw new ServiceAuthError(401, 'invalid_token', 'Authorization header is required.');
+  }
+  const [scheme, token] = header.split(/\s+/, 2);
+  if (!token) {
+    throw new ServiceAuthError(401, 'invalid_token', 'Authorization header is malformed.');
+  }
+  if (scheme === 'Bearer') return { scheme: 'Bearer', token };
+  if (scheme === 'DPoP') return { scheme: 'DPoP', token };
+  throw new ServiceAuthError(401, 'invalid_token', 'Unsupported authorization scheme.');
+};
+
+const verifyAccessToken = async (
+  token: string,
+  ports: ServiceAuthPorts,
+  issuer: string,
+  resource: string
+): Promise<JWTPayload & { scope?: unknown; client_id?: unknown; cnf?: { jkt?: string } }> => {
+  let kid: string | undefined;
+  try {
+    kid = decodeProtectedHeader(token).kid;
+  } catch {
+    throw new ServiceAuthError(401, 'invalid_token', 'Access token header is invalid.');
+  }
+  if (!kid) {
+    throw new ServiceAuthError(401, 'invalid_token', 'Access token is missing a key id.');
+  }
+
+  const key = await ports.jwks.findKeyByKid(kid);
+  if (!key) {
+    throw new ServiceAuthError(401, 'invalid_token', 'Access token signing key is unknown.');
+  }
+
+  const publicKey = await importJWK(key.publicJwk, key.alg);
+  const currentDate = ports.clock.now();
+  try {
+    const { payload } = await jwtVerify(token, publicKey, {
+      audience: resource,
+      currentDate,
+      issuer,
+    });
+    return payload;
+  } catch {
+    throw new ServiceAuthError(401, 'invalid_token', 'Access token is invalid, expired, or has the wrong audience.');
+  }
+};
+
+const parseScopes = (scope: unknown): string[] =>
+  typeof scope === 'string' ? scope.split(/\s+/).filter(Boolean) : [];
+
+const assertScopes = (scopes: string[], requiredScopes: string[]): void => {
+  const granted = new Set(scopes);
+  const missing = requiredScopes.filter((scope) => !granted.has(scope));
+  if (missing.length > 0) {
+    throw new ServiceAuthError(403, 'insufficient_scope', `Missing required scope: ${missing.join(' ')}.`);
+  }
+};
+
+const enforceDpop = async (
+  c: Context,
+  payload: { cnf?: { jkt?: string } },
+  accessToken: string,
+  scheme: 'Bearer' | 'DPoP',
+  options: CreateRequireServiceAuthOptions
+): Promise<string | null> => {
+  const boundJkt = payload.cnf?.jkt;
+  if (!boundJkt) return null;
+
+  if (scheme !== 'DPoP') {
+    throw new ServiceAuthError(401, 'invalid_token', 'DPoP-bound token requires the DPoP authorization scheme.', 'DPoP');
+  }
+
+  const proof = c.req.header('dpop');
+  if (!proof) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP proof is required.', 'DPoP');
+  }
+
+  const verifiedJkt = await verifyServiceDpopProof({
+    accessToken,
+    htm: c.req.method,
+    htu: c.req.url,
+    iatSkewSeconds: options.dpopIatSkewSeconds,
+    ports: options.ports,
+    proof,
+  });
+
+  if (verifiedJkt !== boundJkt) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP proof key does not match the bound token.', 'DPoP');
+  }
+
+  return verifiedJkt;
+};
+
+interface VerifyServiceDpopProofOptions {
+  accessToken: string;
+  htm: string;
+  htu: string;
+  iatSkewSeconds?: number;
+  ports: ServiceAuthPorts;
+  proof: string;
+}
+
+const verifyServiceDpopProof = async (options: VerifyServiceDpopProofOptions): Promise<string> => {
+  const header = decodeProtectedHeader(options.proof);
+  const publicJwk = header.jwk as JWK | undefined;
+  if (!publicJwk || !header.alg || header.typ !== 'dpop+jwt') {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP proof header is invalid.', 'DPoP');
+  }
+
+  const key = await importJWK(publicJwk, header.alg);
+  let payload: JWTPayload;
+  try {
+    ({ payload } = await jwtVerify(options.proof, key));
+  } catch {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP proof signature is invalid.', 'DPoP');
+  }
+
+  const skew = options.iatSkewSeconds ?? 60;
+  if (payload.htm !== options.htm.toUpperCase()) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP htm claim does not match the request method.', 'DPoP');
+  }
+  if (payload.htu !== options.htu) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP htu claim does not match the request URL.', 'DPoP');
+  }
+  if (!payload.jti || typeof payload.jti !== 'string') {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP jti claim is required.', 'DPoP');
+  }
+  if (typeof payload.iat !== 'number') {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP iat claim is required.', 'DPoP');
+  }
+  const nowSeconds = Math.floor(options.ports.clock.now().getTime() / 1000);
+  if (Math.abs(payload.iat - nowSeconds) > skew) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP iat claim is outside the allowed skew.', 'DPoP');
+  }
+
+  // RFC 9449 §4.3: bind the proof to the access token (BR39d-D7).
+  if (payload.ath !== (await sha256Base64url(options.accessToken))) {
+    throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP ath claim does not match the access token.', 'DPoP');
+  }
+
+  if (options.ports.dpopReplay) {
+    const expiresAt = options.ports.clock.addSeconds(options.ports.clock.now(), skew);
+    const recorded = await options.ports.dpopReplay.recordDpopJti(payload.jti, expiresAt);
+    if (!recorded) {
+      throw new ServiceAuthError(401, 'invalid_dpop_proof', 'DPoP proof jti was already used.', 'DPoP');
+    }
+  }
+
+  return calculateJwkThumbprint(publicJwk);
+};
+
+const serviceAuthErrorResponse = (c: Context, error: ServiceAuthError): Response => {
+  c.header('WWW-Authenticate', buildWwwAuthenticate(error));
+  return c.json({ error: { code: error.code, message: error.message } }, error.status);
+};
+
+const buildWwwAuthenticate = (error: ServiceAuthError): string => {
+  const params = [`error="${error.code}"`, `error_description="${error.message}"`];
+  return `${error.scheme} ${params.join(', ')}`;
+};
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/u, '');

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,109 @@
+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 ServiceClientRecord {
+  id: string;
+  clientId: string;
+  clientSecretHash: string;
+  displayName: string | null;
+  allowedScopes: string[];
+  resourceIndicators: string[];
+  dpopBoundAccessTokens: boolean;
+  tenantId: string | null;
+  secretRotatedAt: Date | null;
+  createdAt: Date;
+  revokedAt: Date | null;
+}
+
+export interface OauthStateStorePort {
+  findClient(clientId: string): Promise<OauthClientRecord | null>;
+  findServiceClient?(clientId: string): Promise<ServiceClientRecord | 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[]>;
+}