@tdacorp/identity-client 0.1.0 → 0.2.1

package/README.md

@@ -53,6 +53,9 @@ export const GET = createCallbackRoute({
   redirectUri: `${process.env.APP_URL}/api/auth/callback`,
   cookieSecret: process.env.COOKIE_SECRET!,
   onSuccess: async (tokens, idClaims, { returnTo }) => {
+    // returnTo, when present, has already been validated to a same-app
+    // relative path (single leading `/`, never an absolute URL) by
+    // createLoginRoute -- safe to resolve against APP_URL like this.
     const response = NextResponse.redirect(new URL(returnTo ?? '/', process.env.APP_URL))
     // Store tokens.accessToken / tokens.refreshToken in your own session --
     // this package stops at verified claims, session storage is your call.
@@ -61,6 +64,18 @@ export const GET = createCallbackRoute({
 })
 ```
 
+`createLoginRoute` rejects anything but a relative path for `returnTo` --
+an absolute URL, a protocol-relative `//host` value, a backslash, or a
+control character is silently dropped (coerced to `undefined`) rather than
+sealed into the transaction cookie, closing the open-redirect this shape
+would otherwise allow. This validation applies regardless of whether
+`returnTo` came from the default `returnTo` search param or a custom
+`getReturnTo`, since this package has no per-app trusted-origin registry to
+check an absolute URL's origin against. If your app legitimately needs to
+redirect to an absolute URL after login, carry it through your own
+mechanism (a separate cookie your app validates against its own known
+origins) rather than this package's `returnTo`.
+
 Both handlers seal the PKCE verifier and CSRF `state` into an encrypted
 cookie (via `./sealed`'s `seal()`/`unseal()`) rather than storing them in
 plaintext — you never handle that transaction cookie directly.
@@ -119,10 +134,11 @@ const discovery = await fetchDiscovery('https://identity.tdacorp.in')
 deduplication — concurrent callers for the same issuer during a cold start
 share one fetch rather than each firing their own. Before the result is
 trusted, it is validated: the document's `issuer` must match the URL you
-called with, and `jwks_uri` / `token_endpoint` must be https (loopback hosts
-excepted) and same-origin with the issuer. This is what stops a compromised
-edge cache or a cached error page from redirecting key material or the token
-endpoint somewhere untrusted.
+called with, and `jwks_uri` / `token_endpoint` / `authorization_endpoint`
+must be https (loopback hosts excepted) and same-origin with the issuer.
+This is what stops a compromised edge cache or a cached error page from
+redirecting key material, the token endpoint, or the login page itself
+somewhere untrusted.
 
 Most callers reach `fetchDiscovery` indirectly — every function below calls
 it internally.
@@ -160,6 +176,23 @@ const tokens = await exchangeAuthorizationCode({
 })
 ```
 
+If your relying party is registered on the identity platform for
+`client_secret_post` rather than the default `client_secret_basic`, pass
+`clientAuthMethod` so credentials are sent the way the token endpoint
+actually expects them:
+
+```ts
+const tokens = await exchangeAuthorizationCode({
+  issuer: 'https://identity.tdacorp.in',
+  clientId: process.env.IDENTITY_CLIENT_ID!,
+  clientSecret: process.env.IDENTITY_CLIENT_SECRET!,
+  clientAuthMethod: 'client_secret_post',
+  code,
+  redirectUri,
+  codeVerifier,
+})
+```
+
 Refresh (RFC 6749 §6), returning a classified outcome instead of throwing —
 so a transient infrastructure failure is never mistaken for a rejected
 refresh token:
@@ -182,11 +215,13 @@ if (outcome.outcome === 'success') {
 Machine-to-machine calls with no end user use `clientCredentialsGrant` (RFC
 6749 §4.4) instead, always with a confidential `clientSecret` since there is
 no PKCE verifier to authenticate a public client with. A token minted this
-way carries no `sub` and no `roles` claim — verifying it with
-`verifyAccessToken` returns the `kind: 'machine'` variant of
-`VerifiedAccessToken`, distinct from the `kind: 'user'` variant a normal
-login produces, so reading `.sub` or `.roles` off the wrong branch is a
-compile error rather than `undefined`.
+way carries no `sub` — verifying it with `verifyAccessToken` returns the
+`kind: 'machine'` variant of `VerifiedAccessToken`, distinct from the
+`kind: 'user'` variant a normal login produces, so reading `.sub` off the
+wrong branch is a compile error rather than `undefined`. It can still carry a
+`roles` claim: request `roles` in the client_credentials scope and the server
+resolves it against the requesting client itself as the subject, exactly as
+it does for a user token requesting the same scope.
 
 ## Verification
 
@@ -269,12 +304,6 @@ instead.
 
 ## Limitations in v0.1
 
-- **Only `client_secret_basic` client authentication is supported** for the
-  authorization-code exchange (`exchangeAuthorizationCode` sends an HTTP
-  Basic `Authorization` header when a `clientSecret` is given). A relying
-  party configured on TDACorp Identity for `client_secret_post` cannot use
-  `exchangeAuthorizationCode` as-is today — the token endpoint will reject
-  the request.
 - **No built-in fallback for an `indeterminate` `permits()` result.** That is
   `@tdacorp/identity-authz`'s concern, not this package's, but worth knowing
   up front since most integrations hit both together — see that package's

package/dist/{chunk-VJSMXIZB.js → chunk-S5WGUOJA.js}

@@ -35,6 +35,7 @@ function validateDiscoveryDocument(document, issuerUrl) {
   assertHttps(issuerUrl, "issuer");
   assertHttps(document.jwks_uri, "jwks_uri");
   assertHttps(document.token_endpoint, "token_endpoint");
+  assertHttps(document.authorization_endpoint, "authorization_endpoint");
   if (document.issuer !== issuerUrl) {
     throw new Error(`Discovery: document issuer "${document.issuer}" does not match the configured issuer "${issuerUrl}"`);
   }
@@ -45,6 +46,9 @@ function validateDiscoveryDocument(document, issuerUrl) {
   if (new URL(document.token_endpoint).origin !== issuerOrigin) {
     throw new Error(`Discovery: token_endpoint "${document.token_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
   }
+  if (new URL(document.authorization_endpoint).origin !== issuerOrigin) {
+    throw new Error(`Discovery: authorization_endpoint "${document.authorization_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
+  }
 }
 async function fetchDiscovery(issuerUrl) {
   const cached = discoveryCache.get(issuerUrl);
@@ -135,13 +139,16 @@ function toTokenSet(body) {
     scope: body.scope
   };
 }
-async function postTokenRequest(tokenEndpoint, clientId, clientSecret, params) {
+async function postTokenRequest(tokenEndpoint, clientId, clientSecret, clientAuthMethod, params) {
   const body = new URLSearchParams(params);
   const headers = {
     "Content-Type": "application/x-www-form-urlencoded",
     Accept: "application/json"
   };
-  if (clientSecret) {
+  if (clientSecret && clientAuthMethod === "client_secret_post") {
+    body.set("client_id", clientId);
+    body.set("client_secret", clientSecret);
+  } else if (clientSecret) {
     headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
   } else {
     body.set("client_id", clientId);
@@ -153,12 +160,18 @@ async function readTokenResponseBody(response) {
 }
 async function exchangeAuthorizationCode(options) {
   const discovery = await fetchDiscovery(options.issuer);
-  const response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-    grant_type: "authorization_code",
-    code: options.code,
-    redirect_uri: options.redirectUri,
-    code_verifier: options.codeVerifier
-  });
+  const response = await postTokenRequest(
+    discovery.token_endpoint,
+    options.clientId,
+    options.clientSecret,
+    options.clientAuthMethod ?? "client_secret_basic",
+    {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      code_verifier: options.codeVerifier
+    }
+  );
   const body = await readTokenResponseBody(response);
   if (!response.ok || !body || body.error || typeof body.access_token !== "string") {
     throw new TokenRequestError({ status: response.status, error: body?.error, errorDescription: body?.error_description });
@@ -167,10 +180,16 @@ async function exchangeAuthorizationCode(options) {
 }
 async function clientCredentialsGrant(options) {
   const discovery = await fetchDiscovery(options.issuer);
-  const response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-    grant_type: "client_credentials",
-    ...options.scope ? { scope: options.scope } : {}
-  });
+  const response = await postTokenRequest(
+    discovery.token_endpoint,
+    options.clientId,
+    options.clientSecret,
+    options.clientAuthMethod ?? "client_secret_basic",
+    {
+      grant_type: "client_credentials",
+      ...options.scope ? { scope: options.scope } : {}
+    }
+  );
   const body = await readTokenResponseBody(response);
   if (!response.ok || !body || body.error || typeof body.access_token !== "string") {
     throw new TokenRequestError({ status: response.status, error: body?.error, errorDescription: body?.error_description });
@@ -185,10 +204,16 @@ async function refreshTokens(options) {
   let response;
   try {
     const discovery = await fetchDiscovery(options.issuer);
-    response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-      grant_type: "refresh_token",
-      refresh_token: options.refreshToken
-    });
+    response = await postTokenRequest(
+      discovery.token_endpoint,
+      options.clientId,
+      options.clientSecret,
+      options.clientAuthMethod ?? "client_secret_basic",
+      {
+        grant_type: "refresh_token",
+        refresh_token: options.refreshToken
+      }
+    );
   } catch (error) {
     return { outcome: "transient", error };
   }
@@ -301,7 +326,7 @@ async function verifyAccessToken(accessToken, options) {
       errors: [{ code: "malformed-claims", message: "Access token has neither a sub (user) nor an azp (machine client id)" }]
     };
   }
-  return { success: true, data: { kind: "machine", clientId: payload.azp, claims } };
+  return { success: true, data: { kind: "machine", clientId: payload.azp, roles, claims } };
 }
 
 export {

package/dist/index.cjs

@@ -72,6 +72,7 @@ function validateDiscoveryDocument(document, issuerUrl) {
   assertHttps(issuerUrl, "issuer");
   assertHttps(document.jwks_uri, "jwks_uri");
   assertHttps(document.token_endpoint, "token_endpoint");
+  assertHttps(document.authorization_endpoint, "authorization_endpoint");
   if (document.issuer !== issuerUrl) {
     throw new Error(`Discovery: document issuer "${document.issuer}" does not match the configured issuer "${issuerUrl}"`);
   }
@@ -82,6 +83,9 @@ function validateDiscoveryDocument(document, issuerUrl) {
   if (new URL(document.token_endpoint).origin !== issuerOrigin) {
     throw new Error(`Discovery: token_endpoint "${document.token_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
   }
+  if (new URL(document.authorization_endpoint).origin !== issuerOrigin) {
+    throw new Error(`Discovery: authorization_endpoint "${document.authorization_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
+  }
 }
 async function fetchDiscovery(issuerUrl) {
   const cached = discoveryCache.get(issuerUrl);
@@ -172,13 +176,16 @@ function toTokenSet(body) {
     scope: body.scope
   };
 }
-async function postTokenRequest(tokenEndpoint, clientId, clientSecret, params) {
+async function postTokenRequest(tokenEndpoint, clientId, clientSecret, clientAuthMethod, params) {
   const body = new URLSearchParams(params);
   const headers = {
     "Content-Type": "application/x-www-form-urlencoded",
     Accept: "application/json"
   };
-  if (clientSecret) {
+  if (clientSecret && clientAuthMethod === "client_secret_post") {
+    body.set("client_id", clientId);
+    body.set("client_secret", clientSecret);
+  } else if (clientSecret) {
     headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
   } else {
     body.set("client_id", clientId);
@@ -190,12 +197,18 @@ async function readTokenResponseBody(response) {
 }
 async function exchangeAuthorizationCode(options) {
   const discovery = await fetchDiscovery(options.issuer);
-  const response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-    grant_type: "authorization_code",
-    code: options.code,
-    redirect_uri: options.redirectUri,
-    code_verifier: options.codeVerifier
-  });
+  const response = await postTokenRequest(
+    discovery.token_endpoint,
+    options.clientId,
+    options.clientSecret,
+    options.clientAuthMethod ?? "client_secret_basic",
+    {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      code_verifier: options.codeVerifier
+    }
+  );
   const body = await readTokenResponseBody(response);
   if (!response.ok || !body || body.error || typeof body.access_token !== "string") {
     throw new TokenRequestError({ status: response.status, error: body?.error, errorDescription: body?.error_description });
@@ -204,10 +217,16 @@ async function exchangeAuthorizationCode(options) {
 }
 async function clientCredentialsGrant(options) {
   const discovery = await fetchDiscovery(options.issuer);
-  const response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-    grant_type: "client_credentials",
-    ...options.scope ? { scope: options.scope } : {}
-  });
+  const response = await postTokenRequest(
+    discovery.token_endpoint,
+    options.clientId,
+    options.clientSecret,
+    options.clientAuthMethod ?? "client_secret_basic",
+    {
+      grant_type: "client_credentials",
+      ...options.scope ? { scope: options.scope } : {}
+    }
+  );
   const body = await readTokenResponseBody(response);
   if (!response.ok || !body || body.error || typeof body.access_token !== "string") {
     throw new TokenRequestError({ status: response.status, error: body?.error, errorDescription: body?.error_description });
@@ -222,10 +241,16 @@ async function refreshTokens(options) {
   let response;
   try {
     const discovery = await fetchDiscovery(options.issuer);
-    response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-      grant_type: "refresh_token",
-      refresh_token: options.refreshToken
-    });
+    response = await postTokenRequest(
+      discovery.token_endpoint,
+      options.clientId,
+      options.clientSecret,
+      options.clientAuthMethod ?? "client_secret_basic",
+      {
+        grant_type: "refresh_token",
+        refresh_token: options.refreshToken
+      }
+    );
   } catch (error) {
     return { outcome: "transient", error };
   }
@@ -338,7 +363,7 @@ async function verifyAccessToken(accessToken, options) {
       errors: [{ code: "malformed-claims", message: "Access token has neither a sub (user) nor an azp (machine client id)" }]
     };
   }
-  return { success: true, data: { kind: "machine", clientId: payload.azp, claims } };
+  return { success: true, data: { kind: "machine", clientId: payload.azp, roles, claims } };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { createRemoteJWKSet } from 'jose';
-export { A as AuthorizationCodeExchangeOptions, C as CLOCK_SKEW_TOLERANCE_SECONDS, a as ClientCredentialsGrantOptions, I as IdTokenClaims, R as RefreshTokensOptions, T as TokenRefreshOutcome, b as TokenRequestError, c as TokenSet, d as TokenVerificationError, e as TokenVerificationErrorCode, V as VerificationResult, f as VerifiedAccessToken, g as VerifyTokenOptions, h as clientCredentialsGrant, i as exchangeAuthorizationCode, r as refreshTokens, v as verifyAccessToken, j as verifyIdToken } from './verify-BiGhwaIz.cjs';
+export { A as AuthorizationCodeExchangeOptions, C as CLOCK_SKEW_TOLERANCE_SECONDS, a as ClientCredentialsGrantOptions, I as IdTokenClaims, R as RefreshTokensOptions, T as TokenEndpointAuthMethod, b as TokenRefreshOutcome, c as TokenRequestError, d as TokenSet, e as TokenVerificationError, f as TokenVerificationErrorCode, V as VerificationResult, g as VerifiedAccessToken, h as VerifyTokenOptions, i as clientCredentialsGrant, j as exchangeAuthorizationCode, r as refreshTokens, v as verifyAccessToken, k as verifyIdToken } from './verify-C1Ga6JbS.cjs';
 import '@tdacorp/identity-authz';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { createRemoteJWKSet } from 'jose';
-export { A as AuthorizationCodeExchangeOptions, C as CLOCK_SKEW_TOLERANCE_SECONDS, a as ClientCredentialsGrantOptions, I as IdTokenClaims, R as RefreshTokensOptions, T as TokenRefreshOutcome, b as TokenRequestError, c as TokenSet, d as TokenVerificationError, e as TokenVerificationErrorCode, V as VerificationResult, f as VerifiedAccessToken, g as VerifyTokenOptions, h as clientCredentialsGrant, i as exchangeAuthorizationCode, r as refreshTokens, v as verifyAccessToken, j as verifyIdToken } from './verify-BiGhwaIz.js';
+export { A as AuthorizationCodeExchangeOptions, C as CLOCK_SKEW_TOLERANCE_SECONDS, a as ClientCredentialsGrantOptions, I as IdTokenClaims, R as RefreshTokensOptions, T as TokenEndpointAuthMethod, b as TokenRefreshOutcome, c as TokenRequestError, d as TokenSet, e as TokenVerificationError, f as TokenVerificationErrorCode, V as VerificationResult, g as VerifiedAccessToken, h as VerifyTokenOptions, i as clientCredentialsGrant, j as exchangeAuthorizationCode, r as refreshTokens, v as verifyAccessToken, k as verifyIdToken } from './verify-C1Ga6JbS.js';
 import '@tdacorp/identity-authz';
 
 /**

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   refreshTokens,
   verifyAccessToken,
   verifyIdToken
-} from "./chunk-VJSMXIZB.js";
+} from "./chunk-S5WGUOJA.js";
 export {
   CLOCK_SKEW_TOLERANCE_SECONDS,
   TokenRequestError,

package/dist/next.cjs

@@ -63,6 +63,7 @@ function validateDiscoveryDocument(document, issuerUrl) {
   assertHttps(issuerUrl, "issuer");
   assertHttps(document.jwks_uri, "jwks_uri");
   assertHttps(document.token_endpoint, "token_endpoint");
+  assertHttps(document.authorization_endpoint, "authorization_endpoint");
   if (document.issuer !== issuerUrl) {
     throw new Error(`Discovery: document issuer "${document.issuer}" does not match the configured issuer "${issuerUrl}"`);
   }
@@ -73,6 +74,9 @@ function validateDiscoveryDocument(document, issuerUrl) {
   if (new URL(document.token_endpoint).origin !== issuerOrigin) {
     throw new Error(`Discovery: token_endpoint "${document.token_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
   }
+  if (new URL(document.authorization_endpoint).origin !== issuerOrigin) {
+    throw new Error(`Discovery: authorization_endpoint "${document.authorization_endpoint}" is not same-origin as issuer "${issuerUrl}"`);
+  }
 }
 async function fetchDiscovery(issuerUrl) {
   const cached = discoveryCache.get(issuerUrl);
@@ -163,13 +167,16 @@ function toTokenSet(body) {
     scope: body.scope
   };
 }
-async function postTokenRequest(tokenEndpoint, clientId, clientSecret, params) {
+async function postTokenRequest(tokenEndpoint, clientId, clientSecret, clientAuthMethod, params) {
   const body = new URLSearchParams(params);
   const headers = {
     "Content-Type": "application/x-www-form-urlencoded",
     Accept: "application/json"
   };
-  if (clientSecret) {
+  if (clientSecret && clientAuthMethod === "client_secret_post") {
+    body.set("client_id", clientId);
+    body.set("client_secret", clientSecret);
+  } else if (clientSecret) {
     headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
   } else {
     body.set("client_id", clientId);
@@ -181,12 +188,18 @@ async function readTokenResponseBody(response) {
 }
 async function exchangeAuthorizationCode(options) {
   const discovery = await fetchDiscovery(options.issuer);
-  const response = await postTokenRequest(discovery.token_endpoint, options.clientId, options.clientSecret, {
-    grant_type: "authorization_code",
-    code: options.code,
-    redirect_uri: options.redirectUri,
-    code_verifier: options.codeVerifier
-  });
+  const response = await postTokenRequest(
+    discovery.token_endpoint,
+    options.clientId,
+    options.clientSecret,
+    options.clientAuthMethod ?? "client_secret_basic",
+    {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      code_verifier: options.codeVerifier
+    }
+  );
   const body = await readTokenResponseBody(response);
   if (!response.ok || !body || body.error || typeof body.access_token !== "string") {
     throw new TokenRequestError({ status: response.status, error: body?.error, errorDescription: body?.error_description });
@@ -347,6 +360,17 @@ async function unseal(sealedValue, options) {
 var TRANSACTION_TTL_SECONDS = 600;
 var DEFAULT_TRANSACTION_COOKIE = "identity_oauth_txn";
 var TRANSACTION_PURPOSE = "identity-client:oauth-transaction";
+function sanitizeReturnTo(returnTo) {
+  if (!returnTo) return void 0;
+  if (/[\x00-\x1f]/.test(returnTo)) return void 0;
+  if (returnTo.startsWith("//")) return void 0;
+  if (returnTo.includes("\\")) return void 0;
+  const lower = returnTo.toLowerCase().trim();
+  if (lower.startsWith("javascript:") || lower.startsWith("data:") || lower.startsWith("vbscript:") || lower.startsWith("file:")) {
+    return void 0;
+  }
+  return returnTo.startsWith("/") ? returnTo : void 0;
+}
 function transactionCookieOptions(maxAge) {
   return {
     httpOnly: true,
@@ -361,7 +385,8 @@ function createLoginRoute(config) {
     const state = generateState();
     const codeVerifier = generateCodeVerifier();
     const codeChallenge = await generateCodeChallenge(codeVerifier);
-    const returnTo = config.getReturnTo?.(request) ?? request.nextUrl.searchParams.get("returnTo") ?? void 0;
+    const rawReturnTo = config.getReturnTo?.(request) ?? request.nextUrl.searchParams.get("returnTo") ?? void 0;
+    const returnTo = sanitizeReturnTo(rawReturnTo);
     const transaction = { state, codeVerifier, returnTo };
     const sealedTransaction = await seal(transaction, {
       secret: config.cookieSecret,

package/dist/next.d.cts

@@ -1,5 +1,5 @@
 import { NextResponse, NextRequest } from 'next/server';
-import { c as TokenSet, I as IdTokenClaims } from './verify-BiGhwaIz.cjs';
+import { d as TokenSet, I as IdTokenClaims } from './verify-C1Ga6JbS.cjs';
 import { SealSecret } from './sealed.cjs';
 import '@tdacorp/identity-authz';
 import 'jose';
@@ -22,7 +22,14 @@ interface CreateLoginRouteConfig {
     cookieSecret: SealSecret;
     transactionCookieName?: string;
     /** Where to send the user after login completes. Defaults to reading a
-     *  `returnTo` search param off the incoming request. */
+     *  `returnTo` search param off the incoming request. Validated to a
+     *  same-app relative path (single leading `/`, no `//` prefix, no
+     *  backslash, no C0 control character, no `javascript:`/`data:`/
+     *  `vbscript:`/`file:` scheme) before being sealed into the transaction
+     *  cookie -- see `sanitizeReturnTo`. An invalid value is silently coerced
+     *  to `undefined` rather than rejected with an error, since this package
+     *  has no per-app trusted-origin registry to validate an absolute URL
+     *  against and a bad `returnTo` shouldn't break the login flow. */
     getReturnTo?: (request: NextRequest) => string | undefined;
 }
 /** Builds a GET Route Handler that starts the OIDC login: generates PKCE and
@@ -67,7 +74,10 @@ interface CreateCallbackRouteConfig {
      * Called once the code has been exchanged and the id_token verified. This
      * package does not decide what happens next -- session creation, cookie
      * choice, redirect target are the consuming app's own concerns -- so this
-     * callback's return value IS the route handler's response.
+     * callback's return value IS the route handler's response. `ctx.returnTo`,
+     * if present, already passed `sanitizeReturnTo`'s validation in
+     * `createLoginRoute`, so it is always a same-app relative path, never an
+     * absolute URL -- safe to pass straight into `new URL(returnTo, base)`.
      */
     onSuccess: (tokens: TokenSet, claims: IdTokenClaims, ctx: {
         returnTo?: string;

package/dist/next.d.ts

@@ -1,5 +1,5 @@
 import { NextResponse, NextRequest } from 'next/server';
-import { c as TokenSet, I as IdTokenClaims } from './verify-BiGhwaIz.js';
+import { d as TokenSet, I as IdTokenClaims } from './verify-C1Ga6JbS.js';
 import { SealSecret } from './sealed.js';
 import '@tdacorp/identity-authz';
 import 'jose';
@@ -22,7 +22,14 @@ interface CreateLoginRouteConfig {
     cookieSecret: SealSecret;
     transactionCookieName?: string;
     /** Where to send the user after login completes. Defaults to reading a
-     *  `returnTo` search param off the incoming request. */
+     *  `returnTo` search param off the incoming request. Validated to a
+     *  same-app relative path (single leading `/`, no `//` prefix, no
+     *  backslash, no C0 control character, no `javascript:`/`data:`/
+     *  `vbscript:`/`file:` scheme) before being sealed into the transaction
+     *  cookie -- see `sanitizeReturnTo`. An invalid value is silently coerced
+     *  to `undefined` rather than rejected with an error, since this package
+     *  has no per-app trusted-origin registry to validate an absolute URL
+     *  against and a bad `returnTo` shouldn't break the login flow. */
     getReturnTo?: (request: NextRequest) => string | undefined;
 }
 /** Builds a GET Route Handler that starts the OIDC login: generates PKCE and
@@ -67,7 +74,10 @@ interface CreateCallbackRouteConfig {
      * Called once the code has been exchanged and the id_token verified. This
      * package does not decide what happens next -- session creation, cookie
      * choice, redirect target are the consuming app's own concerns -- so this
-     * callback's return value IS the route handler's response.
+     * callback's return value IS the route handler's response. `ctx.returnTo`,
+     * if present, already passed `sanitizeReturnTo`'s validation in
+     * `createLoginRoute`, so it is always a same-app relative path, never an
+     * absolute URL -- safe to pass straight into `new URL(returnTo, base)`.
      */
     onSuccess: (tokens: TokenSet, claims: IdTokenClaims, ctx: {
         returnTo?: string;

package/dist/next.js

@@ -5,7 +5,7 @@ import {
   generateCodeVerifier,
   generateState,
   verifyIdToken
-} from "./chunk-VJSMXIZB.js";
+} from "./chunk-S5WGUOJA.js";
 import {
   seal,
   unseal
@@ -16,6 +16,17 @@ import { NextResponse } from "next/server";
 var TRANSACTION_TTL_SECONDS = 600;
 var DEFAULT_TRANSACTION_COOKIE = "identity_oauth_txn";
 var TRANSACTION_PURPOSE = "identity-client:oauth-transaction";
+function sanitizeReturnTo(returnTo) {
+  if (!returnTo) return void 0;
+  if (/[\x00-\x1f]/.test(returnTo)) return void 0;
+  if (returnTo.startsWith("//")) return void 0;
+  if (returnTo.includes("\\")) return void 0;
+  const lower = returnTo.toLowerCase().trim();
+  if (lower.startsWith("javascript:") || lower.startsWith("data:") || lower.startsWith("vbscript:") || lower.startsWith("file:")) {
+    return void 0;
+  }
+  return returnTo.startsWith("/") ? returnTo : void 0;
+}
 function transactionCookieOptions(maxAge) {
   return {
     httpOnly: true,
@@ -30,7 +41,8 @@ function createLoginRoute(config) {
     const state = generateState();
     const codeVerifier = generateCodeVerifier();
     const codeChallenge = await generateCodeChallenge(codeVerifier);
-    const returnTo = config.getReturnTo?.(request) ?? request.nextUrl.searchParams.get("returnTo") ?? void 0;
+    const rawReturnTo = config.getReturnTo?.(request) ?? request.nextUrl.searchParams.get("returnTo") ?? void 0;
+    const returnTo = sanitizeReturnTo(rawReturnTo);
     const transaction = { state, codeVerifier, returnTo };
     const sealedTransaction = await seal(transaction, {
       secret: config.cookieSecret,

package/dist/{verify-BiGhwaIz.d.cts → verify-C1Ga6JbS.d.cts}

@@ -31,6 +31,10 @@ declare class TokenRequestError extends Error {
         errorDescription?: string;
     });
 }
+/** The token endpoint client-authentication methods this package supports --
+ *  see RFC 6749 §2.3.1 and OIDC Discovery 1.0's
+ *  `token_endpoint_auth_methods_supported`. */
+type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post';
 /** Options for `exchangeAuthorizationCode`. */
 interface AuthorizationCodeExchangeOptions {
     /** The identity server's issuer URL, used to look up `token_endpoint`. */
@@ -46,6 +50,16 @@ interface AuthorizationCodeExchangeOptions {
     /** The PKCE verifier generated (and kept) alongside the code challenge
      *  sent on the authorization request; see `generateCodeVerifier`. */
     codeVerifier: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 /** RFC 6749 §4.1.3 / RFC 7636 §4.5: exchanges an authorization code for a
  *  token set. Throws `TokenRequestError` on any non-success response. */
@@ -60,6 +74,16 @@ interface ClientCredentialsGrantOptions {
     clientSecret: string;
     /** Space-separated scopes to request for the resulting token. */
     scope?: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 /** RFC 6749 §4.4: mints a token with no end user, for service-to-service
  *  calls. Always confidential -- `clientSecret` is required, not optional,
@@ -75,6 +99,16 @@ interface RefreshTokensOptions {
     clientSecret?: string;
     /** The refresh token to redeem. */
     refreshToken: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 type TokenRefreshOutcome = {
     outcome: 'success';
@@ -144,12 +178,14 @@ declare function refreshTokens(options: RefreshTokensOptions): Promise<TokenRefr
  * read as "no roles" or a machine's `clientId` misread as a user's `sub`.
  *
  * The concrete reason this matters here: this identity server's
- * `client_credentials` grant mints access tokens with no end user and no
- * `roles` claim at all -- there is no subject for a roles claim to describe.
- * Before this type existed, `verifyAccessToken` returned one flat claims
- * object for both cases, so a caller checking `.sub` on a machine token
- * silently got `undefined` instead of a type error telling it this branch
- * has no subject.
+ * `client_credentials` grant mints access tokens with no end user -- there
+ * is no `sub` for this variant, ever. It CAN still carry a `roles` claim,
+ * resolved against the requesting client itself as the subject, whenever the
+ * client_credentials request's scope included `roles`; unlike `sub`, `roles`
+ * is not tied to there being an end user. Before this type existed,
+ * `verifyAccessToken` returned one flat claims object for both cases, so a
+ * caller checking `.sub` on a machine token silently got `undefined` instead
+ * of a type error telling it this branch has no subject.
  */
 type VerifiedAccessToken = {
     kind: 'user';
@@ -162,6 +198,11 @@ type VerifiedAccessToken = {
 } | {
     kind: 'machine';
     clientId: string;
+    /** Present only when the client_credentials request's scope included
+     *  `roles` -- the server resolves the claim against the requesting
+     *  client itself as the subject in that case. Pass to `permits()` from
+     *  `@tdacorp/identity-authz` to decide a permission locally. */
+    roles?: RolesClaim;
     claims: Record<string, unknown>;
 };
 
@@ -303,4 +344,4 @@ declare function verifyIdToken(idToken: string, options: VerifyTokenOptions): Pr
  *  contract as `verifyIdToken`. */
 declare function verifyAccessToken(accessToken: string, options: VerifyTokenOptions): Promise<VerificationResult<VerifiedAccessToken>>;
 
-export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenRefreshOutcome as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, TokenRequestError as b, type TokenSet as c, type TokenVerificationError as d, type TokenVerificationErrorCode as e, type VerifiedAccessToken as f, type VerifyTokenOptions as g, clientCredentialsGrant as h, exchangeAuthorizationCode as i, verifyIdToken as j, refreshTokens as r, verifyAccessToken as v };
+export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenEndpointAuthMethod as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, type TokenRefreshOutcome as b, TokenRequestError as c, type TokenSet as d, type TokenVerificationError as e, type TokenVerificationErrorCode as f, type VerifiedAccessToken as g, type VerifyTokenOptions as h, clientCredentialsGrant as i, exchangeAuthorizationCode as j, verifyIdToken as k, refreshTokens as r, verifyAccessToken as v };

package/dist/{verify-BiGhwaIz.d.ts → verify-C1Ga6JbS.d.ts}

@@ -31,6 +31,10 @@ declare class TokenRequestError extends Error {
         errorDescription?: string;
     });
 }
+/** The token endpoint client-authentication methods this package supports --
+ *  see RFC 6749 §2.3.1 and OIDC Discovery 1.0's
+ *  `token_endpoint_auth_methods_supported`. */
+type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post';
 /** Options for `exchangeAuthorizationCode`. */
 interface AuthorizationCodeExchangeOptions {
     /** The identity server's issuer URL, used to look up `token_endpoint`. */
@@ -46,6 +50,16 @@ interface AuthorizationCodeExchangeOptions {
     /** The PKCE verifier generated (and kept) alongside the code challenge
      *  sent on the authorization request; see `generateCodeVerifier`. */
     codeVerifier: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 /** RFC 6749 §4.1.3 / RFC 7636 §4.5: exchanges an authorization code for a
  *  token set. Throws `TokenRequestError` on any non-success response. */
@@ -60,6 +74,16 @@ interface ClientCredentialsGrantOptions {
     clientSecret: string;
     /** Space-separated scopes to request for the resulting token. */
     scope?: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 /** RFC 6749 §4.4: mints a token with no end user, for service-to-service
  *  calls. Always confidential -- `clientSecret` is required, not optional,
@@ -75,6 +99,16 @@ interface RefreshTokensOptions {
     clientSecret?: string;
     /** The refresh token to redeem. */
     refreshToken: string;
+    /** How to send `clientSecret` to the token endpoint. Defaults to
+     *  `'client_secret_basic'`, which is this package's original and only
+     *  behavior -- omitting this field changes nothing for an existing caller.
+     *  Set it to `'client_secret_post'` if the relying party is registered on
+     *  the identity platform for that method instead: sending Basic auth to a
+     *  `client_secret_post`-only client gets `invalid_client` back, since the
+     *  token endpoint never receives credentials in the form it expects. An
+     *  issuer's OIDC discovery document's `token_endpoint_auth_methods_supported`
+     *  says which methods it actually accepts. */
+    clientAuthMethod?: TokenEndpointAuthMethod;
 }
 type TokenRefreshOutcome = {
     outcome: 'success';
@@ -144,12 +178,14 @@ declare function refreshTokens(options: RefreshTokensOptions): Promise<TokenRefr
  * read as "no roles" or a machine's `clientId` misread as a user's `sub`.
  *
  * The concrete reason this matters here: this identity server's
- * `client_credentials` grant mints access tokens with no end user and no
- * `roles` claim at all -- there is no subject for a roles claim to describe.
- * Before this type existed, `verifyAccessToken` returned one flat claims
- * object for both cases, so a caller checking `.sub` on a machine token
- * silently got `undefined` instead of a type error telling it this branch
- * has no subject.
+ * `client_credentials` grant mints access tokens with no end user -- there
+ * is no `sub` for this variant, ever. It CAN still carry a `roles` claim,
+ * resolved against the requesting client itself as the subject, whenever the
+ * client_credentials request's scope included `roles`; unlike `sub`, `roles`
+ * is not tied to there being an end user. Before this type existed,
+ * `verifyAccessToken` returned one flat claims object for both cases, so a
+ * caller checking `.sub` on a machine token silently got `undefined` instead
+ * of a type error telling it this branch has no subject.
  */
 type VerifiedAccessToken = {
     kind: 'user';
@@ -162,6 +198,11 @@ type VerifiedAccessToken = {
 } | {
     kind: 'machine';
     clientId: string;
+    /** Present only when the client_credentials request's scope included
+     *  `roles` -- the server resolves the claim against the requesting
+     *  client itself as the subject in that case. Pass to `permits()` from
+     *  `@tdacorp/identity-authz` to decide a permission locally. */
+    roles?: RolesClaim;
     claims: Record<string, unknown>;
 };
 
@@ -303,4 +344,4 @@ declare function verifyIdToken(idToken: string, options: VerifyTokenOptions): Pr
  *  contract as `verifyIdToken`. */
 declare function verifyAccessToken(accessToken: string, options: VerifyTokenOptions): Promise<VerificationResult<VerifiedAccessToken>>;
 
-export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenRefreshOutcome as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, TokenRequestError as b, type TokenSet as c, type TokenVerificationError as d, type TokenVerificationErrorCode as e, type VerifiedAccessToken as f, type VerifyTokenOptions as g, clientCredentialsGrant as h, exchangeAuthorizationCode as i, verifyIdToken as j, refreshTokens as r, verifyAccessToken as v };
+export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenEndpointAuthMethod as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, type TokenRefreshOutcome as b, TokenRequestError as c, type TokenSet as d, type TokenVerificationError as e, type TokenVerificationErrorCode as f, type VerifiedAccessToken as g, type VerifyTokenOptions as h, clientCredentialsGrant as i, exchangeAuthorizationCode as j, verifyIdToken as k, refreshTokens as r, verifyAccessToken as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdacorp/identity-client",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "OIDC relying-party client for TDACorp Identity: discovery, PKCE, token exchange, token verification and Next.js route helpers.",
   "license": "MIT",
   "bugs": {
@@ -50,17 +50,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@tdacorp/identity-authz": "workspace:*",
-    "jose": "^6.2.9"
+    "jose": "^6.2.9",
+    "@tdacorp/identity-authz": "^0.2.0"
   },
   "peerDependencies": {
     "next": ">=14"
@@ -71,10 +66,15 @@
     }
   },
   "devDependencies": {
-    "@tdacorp/typescript-config": "workspace:*",
     "next": "^16.3.2",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@tdacorp/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}