@oauth-spa-kit/core 1.0.0 → 1.0.2

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.
package/README.md ADDED
@@ -0,0 +1,52 @@
1
+ # @oauth-spa-kit/core
2
+
3
+ Framework- and runtime-agnostic OAuth 2.1 / OIDC primitives -- PKCE, discovery,
4
+ DPoP proofs, `private_key_jwt` client assertions, PAR, token exchange -- plus
5
+ a `fetch`-based session client. Only Web Crypto + `fetch`, no DOM or
6
+ Node-only APIs, so the same code runs in the browser and inside
7
+ [`@oauth-spa-kit/server`](https://www.npmjs.com/package/@oauth-spa-kit/server).
8
+
9
+ Part of [oauth-spa-kit](https://github.com/ehncraft/oauth-spa-kit) -- see the
10
+ root README for the full architecture (BFF pattern, no `client_secret`, FAPI
11
+ 2.0 baseline).
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @oauth-spa-kit/core
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ Most apps won't call this package directly -- pull in
22
+ [`@oauth-spa-kit/server`](https://www.npmjs.com/package/@oauth-spa-kit/server)
23
+ for the BFF route handlers, or
24
+ [`@oauth-spa-kit/react`](https://www.npmjs.com/package/@oauth-spa-kit/react) /
25
+ [`@oauth-spa-kit/nuxt`](https://www.npmjs.com/package/@oauth-spa-kit/nuxt)
26
+ for framework bindings, which both build on this package's
27
+ `createSessionClient()`:
28
+
29
+ ```ts
30
+ import { createSessionClient } from "@oauth-spa-kit/core";
31
+
32
+ const client = createSessionClient({ baseUrl: "/auth" });
33
+
34
+ client.subscribe((state) => {
35
+ // state.ready, state.loggedIn, state.user
36
+ });
37
+
38
+ await client.refresh(); // GET /auth/session
39
+ client.login("/dashboard"); // full-page redirect, no silent/iframe path
40
+ await client.logout();
41
+ ```
42
+
43
+ The lower-level protocol primitives (`createPkceParams`,
44
+ `discoverOidcConfiguration`, `pushAuthorizationRequest`,
45
+ `exchangeAuthorizationCode`, `exchangeRefreshToken`, `generateDpopKeyPair`,
46
+ `verifyJwt`, etc.) are what `@oauth-spa-kit/server`'s handlers are built
47
+ from -- see its README if you're wiring a BFF for a runtime this kit doesn't
48
+ already have an adapter for.
49
+
50
+ ## License
51
+
52
+ MIT
@@ -1,4 +1,4 @@
1
- import type { ClientAuthentication } from "./types";
1
+ import type { ClientAuthentication } from "./types.js";
2
2
  /**
3
3
  * RFC 7523 `private_key_jwt` client assertion -- the form params to attach
4
4
  * alongside `client_id` when authenticating to the token endpoint or the
@@ -1,5 +1,5 @@
1
- import { signJwt } from "./jwt";
2
- import { generateRandomString } from "./pkce";
1
+ import { signJwt } from "./jwt.js";
2
+ import { generateRandomString } from "./pkce.js";
3
3
  /**
4
4
  * RFC 7523 `private_key_jwt` client assertion -- the form params to attach
5
5
  * alongside `client_id` when authenticating to the token endpoint or the
@@ -1,4 +1,4 @@
1
- import type { OidcDiscoveryDocument } from "./types";
1
+ import type { OidcDiscoveryDocument } from "./types.js";
2
2
  /**
3
3
  * Fetch and cache `${issuer}/.well-known/openid-configuration`.
4
4
  * Prefer passing a static `discoveryDocument` in config for providers whose
package/dist/discovery.js CHANGED
@@ -1,4 +1,4 @@
1
- import { DiscoveryError } from "./errors";
1
+ import { DiscoveryError } from "./errors.js";
2
2
  const cache = new Map();
3
3
  const CACHE_TTL_MS = 60 * 60 * 1000; // 1h -- discovery docs change essentially never, but don't cache forever
4
4
  /**
package/dist/dpop.js CHANGED
@@ -1,6 +1,6 @@
1
- import { base64UrlEncode } from "./base64url";
2
- import { signJwt } from "./jwt";
3
- import { generateRandomString } from "./pkce";
1
+ import { base64UrlEncode } from "./base64url.js";
2
+ import { signJwt } from "./jwt.js";
3
+ import { generateRandomString } from "./pkce.js";
4
4
  export async function generateDpopKeyPair() {
5
5
  const { publicKey, privateKey } = await globalThis.crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" },
6
6
  /* extractable */ true, ["sign", "verify"]);
package/dist/index.d.ts CHANGED
@@ -1,12 +1,12 @@
1
- export * from "./types";
2
- export * from "./errors";
3
- export * from "./base64url";
4
- export * from "./pkce";
5
- export * from "./discovery";
6
- export * from "./dpop";
7
- export * from "./jwt";
8
- export * from "./jwks";
9
- export * from "./clientAssertion";
10
- export * from "./par";
11
- export * from "./tokenExchange";
12
- export * from "./sessionClient";
1
+ export * from "./types.js";
2
+ export * from "./errors.js";
3
+ export * from "./base64url.js";
4
+ export * from "./pkce.js";
5
+ export * from "./discovery.js";
6
+ export * from "./dpop.js";
7
+ export * from "./jwt.js";
8
+ export * from "./jwks.js";
9
+ export * from "./clientAssertion.js";
10
+ export * from "./par.js";
11
+ export * from "./tokenExchange.js";
12
+ export * from "./sessionClient.js";
package/dist/index.js CHANGED
@@ -1,12 +1,12 @@
1
- export * from "./types";
2
- export * from "./errors";
3
- export * from "./base64url";
4
- export * from "./pkce";
5
- export * from "./discovery";
6
- export * from "./dpop";
7
- export * from "./jwt";
8
- export * from "./jwks";
9
- export * from "./clientAssertion";
10
- export * from "./par";
11
- export * from "./tokenExchange";
12
- export * from "./sessionClient";
1
+ export * from "./types.js";
2
+ export * from "./errors.js";
3
+ export * from "./base64url.js";
4
+ export * from "./pkce.js";
5
+ export * from "./discovery.js";
6
+ export * from "./dpop.js";
7
+ export * from "./jwt.js";
8
+ export * from "./jwks.js";
9
+ export * from "./clientAssertion.js";
10
+ export * from "./par.js";
11
+ export * from "./tokenExchange.js";
12
+ export * from "./sessionClient.js";
package/dist/jwks.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import type { Jwks } from "./jwt";
1
+ import type { Jwks } from "./jwt.js";
2
2
  export declare function fetchJwks(jwksUri: string, fetchImpl?: typeof fetch): Promise<Jwks>;
package/dist/jwks.js CHANGED
@@ -1,4 +1,4 @@
1
- import { DiscoveryError } from "./errors";
1
+ import { DiscoveryError } from "./errors.js";
2
2
  const cache = new Map();
3
3
  const CACHE_TTL_MS = 60 * 60 * 1000;
4
4
  export async function fetchJwks(jwksUri, fetchImpl = fetch) {
package/dist/jwt.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { OAuthError } from "./errors";
1
+ import { OAuthError } from "./errors.js";
2
2
  /**
3
3
  * PS256 (RSA-PSS) and ES256 (ECDSA P-256) only -- no RS256. FAPI 2.0
4
4
  * Security Profile requires PS256 or ES256 for asymmetric client/request
@@ -24,6 +24,15 @@ export interface Jwks {
24
24
  alg?: string;
25
25
  })[];
26
26
  }
27
+ /**
28
+ * Import a `private_key_jwt` signing key from its JWK form. Non-extractable,
29
+ * matching the doc comment on `ClientAuthentication.privateKey` in types.ts
30
+ * -- for config paths that can only carry JSON-serializable values (e.g.
31
+ * `@oauth-spa-kit/nuxt`'s runtimeConfig, which a live `CryptoKey` doesn't
32
+ * survive), so the JWK travels through config and gets imported once
33
+ * server-side instead.
34
+ */
35
+ export declare function importClientAssertionPrivateKey(jwk: JsonWebKey, alg: JwtAlgorithm): Promise<CryptoKey>;
27
36
  export interface VerifyJwtArgs {
28
37
  token: string;
29
38
  jwks: Jwks;
package/dist/jwt.js CHANGED
@@ -1,5 +1,5 @@
1
- import { base64UrlDecode, base64UrlDecodeJson, base64UrlEncode, base64UrlEncodeJson } from "./base64url";
2
- import { OAuthError } from "./errors";
1
+ import { base64UrlDecode, base64UrlDecodeJson, base64UrlEncode, base64UrlEncodeJson } from "./base64url.js";
2
+ import { OAuthError } from "./errors.js";
3
3
  export class JwtVerificationError extends OAuthError {
4
4
  constructor(message) {
5
5
  super(message);
@@ -27,6 +27,17 @@ export async function signJwt({ header = {}, payload, privateKey, alg }) {
27
27
  async function importVerificationKey(jwk, alg) {
28
28
  return globalThis.crypto.subtle.importKey("jwk", jwk, importParams(alg), false, ["verify"]);
29
29
  }
30
+ /**
31
+ * Import a `private_key_jwt` signing key from its JWK form. Non-extractable,
32
+ * matching the doc comment on `ClientAuthentication.privateKey` in types.ts
33
+ * -- for config paths that can only carry JSON-serializable values (e.g.
34
+ * `@oauth-spa-kit/nuxt`'s runtimeConfig, which a live `CryptoKey` doesn't
35
+ * survive), so the JWK travels through config and gets imported once
36
+ * server-side instead.
37
+ */
38
+ export async function importClientAssertionPrivateKey(jwk, alg) {
39
+ return globalThis.crypto.subtle.importKey("jwk", jwk, importParams(alg), false, ["sign"]);
40
+ }
30
41
  function algFromJwtHeader(header) {
31
42
  if (header.alg === "PS256" || header.alg === "ES256")
32
43
  return header.alg;
package/dist/par.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { ClientAuthentication } from "./types";
1
+ import type { ClientAuthentication } from "./types.js";
2
2
  /**
3
3
  * RFC 9126 Pushed Authorization Requests -- required by FAPI 2.0. Instead
4
4
  * of redirecting the browser to `/authorize` with every parameter
package/dist/par.js CHANGED
@@ -1,5 +1,5 @@
1
- import { buildClientAssertionParams } from "./clientAssertion";
2
- import { OAuthError } from "./errors";
1
+ import { buildClientAssertionParams } from "./clientAssertion.js";
2
+ import { OAuthError } from "./errors.js";
3
3
  export async function pushAuthorizationRequest(args) {
4
4
  const fetchImpl = args.fetchImpl ?? fetch;
5
5
  const assertionParams = await buildClientAssertionParams(args.clientId, args.clientAuthentication, args.assertionAudience);
package/dist/pkce.js CHANGED
@@ -7,7 +7,7 @@
7
7
  * authorization-code clients, public or confidential, so this always runs,
8
8
  * never treated as optional.
9
9
  */
10
- import { base64UrlEncode } from "./base64url";
10
+ import { base64UrlEncode } from "./base64url.js";
11
11
  function randomBytes(length) {
12
12
  const bytes = new Uint8Array(length);
13
13
  globalThis.crypto.getRandomValues(bytes);
@@ -1,4 +1,4 @@
1
- import type { SessionState } from "./types";
1
+ import type { SessionState } from "./types.js";
2
2
  /**
3
3
  * Browser-side session client for the BFF pattern: the SPA never sees an
4
4
  * access or refresh token, only a same-origin `/auth/session` JSON endpoint
@@ -1,5 +1,5 @@
1
- import { type DpopKeyPair } from "./dpop";
2
- import type { OAuthClientConfig, TokenResponse, TokenSet } from "./types";
1
+ import { type DpopKeyPair } from "./dpop.js";
2
+ import type { OAuthClientConfig, TokenResponse, TokenSet } from "./types.js";
3
3
  export declare function toTokenSet(response: TokenResponse): TokenSet;
4
4
  export interface ExchangeAuthorizationCodeArgs {
5
5
  config: OAuthClientConfig;
@@ -1,6 +1,6 @@
1
- import { buildClientAssertionParams } from "./clientAssertion";
2
- import { createDpopProof, generateDpopKeyPair } from "./dpop";
3
- import { TokenExchangeError } from "./errors";
1
+ import { buildClientAssertionParams } from "./clientAssertion.js";
2
+ import { createDpopProof, generateDpopKeyPair } from "./dpop.js";
3
+ import { TokenExchangeError } from "./errors.js";
4
4
  export function toTokenSet(response) {
5
5
  return {
6
6
  accessToken: response.access_token,
package/dist/types.d.ts CHANGED
@@ -12,7 +12,7 @@ export interface OidcDiscoveryDocument {
12
12
  pushed_authorization_request_endpoint?: string;
13
13
  require_pushed_authorization_requests?: boolean;
14
14
  }
15
- import type { JwtAlgorithm } from "./jwt";
15
+ import type { JwtAlgorithm } from "./jwt.js";
16
16
  /**
17
17
  * Confidential-client authentication to the token endpoint, via a signed
18
18
  * JWT assertion (RFC 7523 `private_key_jwt`) -- never a shared
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oauth-spa-kit/core",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
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": {