@oauth-spa-kit/core 1.2.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,9 +6,28 @@ import type { ClientAuthentication } from "./types.js";
6
6
  * supports; there is no client_secret fallback (see the comment on
7
7
  * `ClientAuthentication` in types.ts for why).
8
8
  *
9
- * `audience` is conventionally the URL of the endpoint being authenticated
10
- * to (OIDC Core section 9); a few authorization servers expect the issuer
11
- * identifier instead regardless of which endpoint is called -- check your
12
- * AS's docs if it rejects the assertion with an audience error.
9
+ * `audience` MUST be the authorization server's issuer identifier
10
+ * ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) as its sole value --
11
+ * per [draft-ietf-oauth-rfc7523bis](https://datatracker.ietf.org/doc/draft-ietf-oauth-rfc7523bis/)
12
+ * section 4, which updates RFC 7523 specifically to close an audience
13
+ * injection vulnerability (disclosed January 2025): a token-endpoint URL
14
+ * (the older, now-superseded convention) or any other endpoint-specific
15
+ * value MUST NOT be used, and a compliant AS MUST reject an assertion that
16
+ * doesn't carry its issuer identifier as the sole `aud`. This kit's own
17
+ * callers (`packages/server/src/handlers.ts`) always pass the discovery
18
+ * document's `issuer` for this reason. If an AS rejects a valid assertion
19
+ * with an audience error, the AS is non-compliant with the current spec --
20
+ * `audience` here is deliberately not defaulted so a caller integrating
21
+ * with such an AS still has to pass a value explicitly, rather than this
22
+ * kit silently reintroducing an obsolete pattern.
23
+ *
24
+ * The JWT header is also explicitly typed `client-authentication+jwt`,
25
+ * rfc7523bis section 3.2's recommended (SHOULD) explicit type for this
26
+ * assertion class -- RFC 8725 section 3.11 explicit typing, applied here to
27
+ * rule out cross-JWT confusion (this token being mistaken for, say, an
28
+ * access token or an `id_token`). The spec itself says a server SHOULD NOT
29
+ * reject an untyped assertion for backward compatibility, but some AS's
30
+ * enforce it as a MUST; setting it unconditionally costs nothing and is
31
+ * forward-compatible either way.
13
32
  */
14
33
  export declare function buildClientAssertionParams(clientId: string, clientAuth: ClientAuthentication, audience: string): Promise<Record<string, string>>;
@@ -7,16 +7,35 @@ import { generateRandomString } from "./pkce.js";
7
7
  * supports; there is no client_secret fallback (see the comment on
8
8
  * `ClientAuthentication` in types.ts for why).
9
9
  *
10
- * `audience` is conventionally the URL of the endpoint being authenticated
11
- * to (OIDC Core section 9); a few authorization servers expect the issuer
12
- * identifier instead regardless of which endpoint is called -- check your
13
- * AS's docs if it rejects the assertion with an audience error.
10
+ * `audience` MUST be the authorization server's issuer identifier
11
+ * ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) as its sole value --
12
+ * per [draft-ietf-oauth-rfc7523bis](https://datatracker.ietf.org/doc/draft-ietf-oauth-rfc7523bis/)
13
+ * section 4, which updates RFC 7523 specifically to close an audience
14
+ * injection vulnerability (disclosed January 2025): a token-endpoint URL
15
+ * (the older, now-superseded convention) or any other endpoint-specific
16
+ * value MUST NOT be used, and a compliant AS MUST reject an assertion that
17
+ * doesn't carry its issuer identifier as the sole `aud`. This kit's own
18
+ * callers (`packages/server/src/handlers.ts`) always pass the discovery
19
+ * document's `issuer` for this reason. If an AS rejects a valid assertion
20
+ * with an audience error, the AS is non-compliant with the current spec --
21
+ * `audience` here is deliberately not defaulted so a caller integrating
22
+ * with such an AS still has to pass a value explicitly, rather than this
23
+ * kit silently reintroducing an obsolete pattern.
24
+ *
25
+ * The JWT header is also explicitly typed `client-authentication+jwt`,
26
+ * rfc7523bis section 3.2's recommended (SHOULD) explicit type for this
27
+ * assertion class -- RFC 8725 section 3.11 explicit typing, applied here to
28
+ * rule out cross-JWT confusion (this token being mistaken for, say, an
29
+ * access token or an `id_token`). The spec itself says a server SHOULD NOT
30
+ * reject an untyped assertion for backward compatibility, but some AS's
31
+ * enforce it as a MUST; setting it unconditionally costs nothing and is
32
+ * forward-compatible either way.
14
33
  */
15
34
  export async function buildClientAssertionParams(clientId, clientAuth, audience) {
16
35
  const now = Math.floor(Date.now() / 1000);
17
36
  const lifetimeSeconds = clientAuth.assertionLifetimeSeconds ?? 60;
18
37
  const assertion = await signJwt({
19
- header: clientAuth.keyId ? { kid: clientAuth.keyId } : {},
38
+ header: { typ: "client-authentication+jwt", ...(clientAuth.keyId ? { kid: clientAuth.keyId } : {}) },
20
39
  payload: {
21
40
  iss: clientId,
22
41
  sub: clientId,
package/dist/par.d.ts CHANGED
@@ -12,7 +12,7 @@ export interface PushAuthorizationRequestArgs {
12
12
  parEndpoint: string;
13
13
  clientId: string;
14
14
  clientAuthentication: ClientAuthentication;
15
- /** Authorization server issuer identifier -- used to look up a client assertion audience if your AS expects it instead of the endpoint URL. Prefer passing the PAR endpoint URL itself unless your AS's docs say otherwise. */
15
+ /** Client assertion `aud` -- pass the AS's issuer identifier (rfc7523bis section 4 mandates this as the sole value; see `buildClientAssertionParams`). */
16
16
  assertionAudience: string;
17
17
  /** Authorization request parameters (response_type, redirect_uri, scope, state, nonce, code_challenge, code_challenge_method, and any extras) -- everything that would otherwise go on the `/authorize` query string. */
18
18
  params: Record<string, string>;
@@ -4,6 +4,8 @@ export declare function toTokenSet(response: TokenResponse): TokenSet;
4
4
  export interface ExchangeAuthorizationCodeArgs {
5
5
  config: OAuthClientConfig;
6
6
  tokenEndpoint: string;
7
+ /** Client assertion `aud` -- pass the AS's issuer identifier (rfc7523bis section 4 mandates this as the sole value; see `buildClientAssertionParams`). */
8
+ assertionAudience: string;
7
9
  code: string;
8
10
  codeVerifier: string;
9
11
  /** Reuse the same key pair used to bind the authorization request, if DPoP was used there too. A fresh one is generated if omitted and `config.dpop !== false`. */
@@ -15,6 +17,8 @@ export declare function exchangeAuthorizationCode(args: ExchangeAuthorizationCod
15
17
  export interface ExchangeRefreshTokenArgs {
16
18
  config: OAuthClientConfig;
17
19
  tokenEndpoint: string;
20
+ /** Client assertion `aud` -- pass the AS's issuer identifier (rfc7523bis section 4 mandates this as the sole value; see `buildClientAssertionParams`). */
21
+ assertionAudience: string;
18
22
  refreshToken: string;
19
23
  dpopKeyPair?: DpopKeyPair;
20
24
  fetchImpl?: typeof fetch;
@@ -51,7 +51,7 @@ async function postToken(args) {
51
51
  /** RFC 6749 section 4.1.3 -- authorization_code grant, PKCE-verified, private_key_jwt-authenticated. */
52
52
  export async function exchangeAuthorizationCode(args) {
53
53
  const fetchImpl = args.fetchImpl ?? fetch;
54
- const assertionParams = await buildClientAssertionParams(args.config.clientId, args.config.clientAuthentication, args.tokenEndpoint);
54
+ const assertionParams = await buildClientAssertionParams(args.config.clientId, args.config.clientAuthentication, args.assertionAudience);
55
55
  const params = new URLSearchParams({
56
56
  grant_type: "authorization_code",
57
57
  client_id: args.config.clientId,
@@ -81,7 +81,7 @@ export async function exchangeAuthorizationCode(args) {
81
81
  */
82
82
  export async function exchangeRefreshToken(args) {
83
83
  const fetchImpl = args.fetchImpl ?? fetch;
84
- const assertionParams = await buildClientAssertionParams(args.config.clientId, args.config.clientAuthentication, args.tokenEndpoint);
84
+ const assertionParams = await buildClientAssertionParams(args.config.clientId, args.config.clientAuthentication, args.assertionAudience);
85
85
  const params = new URLSearchParams({
86
86
  grant_type: "refresh_token",
87
87
  client_id: args.config.clientId,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oauth-spa-kit/core",
3
- "version": "1.2.0",
3
+ "version": "2.0.1",
4
4
  "description": "Framework- and runtime-agnostic OAuth 2.1 / OIDC primitives (PKCE, discovery, token exchange, DPoP) plus a fetch-based session client. Runs in the browser, Node, and edge runtimes -- no DOM or Node-only APIs.",
5
5
  "license": "MIT",
6
6
  "repository": {