@sentropic/auth-hono 0.3.0 → 0.6.0

package/src/oauth/token-handler.ts

@@ -5,7 +5,9 @@ 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';
+import type { AuthCodePayload, OauthClientRecord, ServiceClientRecord, TokenMeta } from './state-store-types.js';
+
+const DEFAULT_SERVICE_ACCESS_TOKEN_TTL_SECONDS = 900;
 
 export interface OAuthTokenHandlerOptions {
   accessTokenTtlSeconds?: number;
@@ -13,6 +15,7 @@ export interface OAuthTokenHandlerOptions {
   idTokenTtlSeconds?: number;
   issuer: string;
   ports: AuthHonoPorts;
+  serviceAccessTokenTtlSeconds?: number;
 }
 
 interface ClientAuthentication {
@@ -20,12 +23,26 @@ interface ClientAuthentication {
   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());
-    if (form.get('grant_type') !== 'authorization_code') {
-      return oauthJsonError(c, 400, 'unsupported_grant_type', 'Only authorization_code grant is supported.');
+    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);
@@ -42,6 +59,9 @@ export const createOAuthTokenHandler =
       return oauthJsonError(c, 400, 'invalid_grant', 'PKCE verification failed.');
     }
 
+    const resourceError = validateTokenResource(c, form, codePayload);
+    if (resourceError) return resourceError;
+
     const dpopJkt = await resolveDpopJkt(c, options, auth.client, codePayload);
     if (dpopJkt instanceof Response) return dpopJkt;
 
@@ -100,6 +120,30 @@ const parseClientCredentials = (
   };
 };
 
+/**
+ * RFC 8707 resource validation on the token leg of the `authorization_code` flow (BR-39l Lot 2).
+ * - C1 single-aud: more than one `resource` value ⇒ `invalid_target`.
+ * - C3 sealing: if the client re-sends `resource` on the token request (the MCP draft requires it
+ *   on both legs), it MUST equal the value sealed at authorize time, else `invalid_grant`
+ *   (audience downgrade/upgrade rejection). The `aud` is derived ONLY from the sealed value.
+ * No `resource` on the token leg is accepted (the sealed value still governs `aud`).
+ */
+const validateTokenResource = (
+  c: Context,
+  form: URLSearchParams,
+  codePayload: AuthCodePayload
+): Response | null => {
+  const requested = form.getAll('resource').filter((value) => value.length > 0);
+  if (requested.length === 0) return null;
+  if (requested.length > 1) {
+    return oauthJsonError(c, 400, 'invalid_target', 'Only a single resource indicator is supported.');
+  }
+  if (requested[0] !== (codePayload.resource ?? null)) {
+    return oauthJsonError(c, 400, 'invalid_grant', 'resource does not match the authorization request.');
+  }
+  return null;
+};
+
 const resolveDpopJkt = async (
   c: Context,
   options: OAuthTokenHandlerOptions,
@@ -131,6 +175,160 @@ const resolveDpopJkt = async (
   }
 };
 
+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,
@@ -145,15 +343,30 @@ const issueTokens = async (
   const idExpiresAt = options.ports.clock.addSeconds(now, idTokenTtlSeconds);
   const scopes = codePayload.scope.split(/\s+/).filter(Boolean);
   const cnf = dpopJkt ? { jkt: dpopJkt } : undefined;
+
+  // BR-39e: bind the tenant claim to a STILL-`approved` membership at token time (lifecycle
+  // gate). If the membership was suspended/revoked between authorize and token exchange, drop
+  // the claim so no tenant-scoped token is issued for a non-member.
+  let boundTenantId: string | null = codePayload.tenantId;
+  if (boundTenantId && options.ports.tenant) {
+    const stillApproved = await options.ports.tenant.isApprovedMember(codePayload.userId, boundTenantId);
+    if (!stillApproved) boundTenantId = null;
+  }
+
   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`;
+  // BR-39l Lot 2 (C3/C4): variable RFC 8707 audience. The access-token `aud` is the resource
+  // sealed at authorize time (single string), or the userinfo URL by default — byte-identical to
+  // auth-hono 0.5.0 when no `resource` was requested. The id_token `aud` (client_id) is untouched.
+  const accessAudience =
+    codePayload.resource ?? `${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 } : {}),
+      ...(boundTenantId ? { tid: boundTenantId } : {}),
       scope: codePayload.scope,
     },
     {
@@ -197,6 +410,7 @@ const issueTokens = async (
         ...(scopes.includes('email') ? { email: user.email, email_verified: user.emailVerified } : {}),
         ...(scopes.includes('profile') ? { name: user.displayName } : {}),
         ...(codePayload.nonce ? { nonce: codePayload.nonce } : {}),
+        ...(boundTenantId ? { tid: boundTenantId } : {}),
       },
       {
         audience: client.clientId,

package/src/oauth/wellknown-handler.ts

@@ -17,10 +17,10 @@ export const createWellKnownRouter = (options: CreateWellKnownRouterOptions): Ho
   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'],
+      claims_supported: ['sub', 'aud', 'iss', 'exp', 'iat', 'nonce', 'auth_time', 'acr', 'email', 'email_verified', 'name', 'tid'],
       code_challenge_methods_supported: ['S256'],
       dpop_signing_alg_values_supported: ['EdDSA'],
-      grant_types_supported: ['authorization_code'],
+      grant_types_supported: ['authorization_code', 'client_credentials'],
       id_token_signing_alg_values_supported: ['EdDSA'],
       introspection_endpoint: `${issuer}${oauthPrefix}/introspect`,
       issuer,
@@ -30,7 +30,7 @@ export const createWellKnownRouter = (options: CreateWellKnownRouterOptions): Ho
       scopes_supported: ['openid', 'profile', 'email'],
       subject_types_supported: ['public'],
       token_endpoint: `${issuer}${oauthPrefix}/token`,
-      token_endpoint_auth_methods_supported: ['client_secret_basic', 'none'],
+      token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],
       userinfo_endpoint: `${issuer}${oauthPrefix}/userinfo`,
     })
   );

package/src/ports.ts

@@ -9,6 +9,7 @@ export type {
   OauthClientRecord,
   OauthStateStorePort,
   OauthTokenType,
+  ServiceClientRecord,
   TokenMeta,
 } from './oauth/state-store-types.js';
 
@@ -286,6 +287,19 @@ export interface AuthHonoAccountPolicyPort {
   afterUserCreated?(user: AuthHonoUserRecord): Promise<void> | void;
 }
 
+/**
+ * BR-39e: tenancy spine. OPTIONAL — when absent, auth-hono keeps the legacy behavior of
+ * sourcing the auth-code `tenantId` from the client. When present, the tenant claim (`tid`)
+ * is derived ONLY from a VALIDATED `approved` membership (never a raw request parameter),
+ * and re-checked at token time (lifecycle gate).
+ */
+export interface AuthHonoTenantPort {
+  /** Tenant ids the user is an `approved` member of, for selection + claim derivation. */
+  listApprovedTenantIds(userId: string): Promise<string[]>;
+  /** True iff (userId, tenantId) is currently an `approved` membership (binding re-check). */
+  isApprovedMember(userId: string, tenantId: string): Promise<boolean>;
+}
+
 export interface AuthHonoPorts {
   users: AuthHonoUserPort;
   credentials: AuthHonoCredentialPort;
@@ -302,4 +316,6 @@ export interface AuthHonoPorts {
   accountPolicy: AuthHonoAccountPolicyPort;
   oauthStateStore: OauthStateStorePort;
   jwks: JwksPort;
+  /** BR-39e tenancy spine (optional; legacy behavior when absent). */
+  tenant?: AuthHonoTenantPort;
 }