@tdacorp/identity-client 0.2.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.
@@ -199,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
 

package/dist/{chunk-6WGVTO7C.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);
@@ -322,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);
@@ -359,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 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-DTUDjR4v.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 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-DTUDjR4v.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-6WGVTO7C.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);
@@ -356,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,
@@ -370,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 { d as TokenSet, I as IdTokenClaims } from './verify-DTUDjR4v.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 { d as TokenSet, I as IdTokenClaims } from './verify-DTUDjR4v.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-6WGVTO7C.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-DTUDjR4v.d.cts → verify-C1Ga6JbS.d.cts}

@@ -178,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';
@@ -196,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>;
 };
 

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

@@ -178,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';
@@ -196,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>;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdacorp/identity-client",
-  "version": "0.2.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": {