@odatnurd/kinde-auth 0.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,24 @@
+name: Publish to NPMJS
+
+on:
+  push:
+    tags:
+      - v*
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'The tag to release, e.g., v1.2.3'
+        required: true
+
+jobs:
+  publish-npm-package-after-testing:
+    permissions:
+      id-token: write
+      contents: write
+    uses: odatnurd/github-workflows/.github/workflows/npm-publish.yaml@npm-publish-v1.0.3
+    with:
+      node-version: 24
+      package-version: ${{ (github.event_name == 'workflow_dispatch' && inputs.tag) || github.ref_name }}
+      create-release: true
+      test-script: 'test'
+      build-script: 'build:prod'

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terence Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# Kinde Auth Helpers
+
+Small library to wrap Kinde Auth; still under heavy development.
+
+> **Stormtrooper:** Let me see your identification.
+>
+> **Obi-Wan:** *(waves hand slightly)* You don't need to see his identification.
+>
+> **Stormtrooper:** We don't need to see his identification.
+>
+> **Obi-Wan:** This isn't the Auth library you're looking for.
+>
+> **Stormtrooper:** This isn't the Auth library we're looking for.
+>
+> **Obi-Wan:** He can go about his business.
+>
+> **Stormtrooper:** You can go about your business.
+>
+> **Obi-Wan:** Move along.
+>
+> **Stormtrooper:** Move along... move along.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@odatnurd/kinde-auth",
+  "version": "0.1.0",
+  "description": "Authentication handling for Kinde auth",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "OdatNurd",
+    "email": "odatnurd@gmail.com",
+    "url": "https://odatnurd.net"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OdatNurd/kinde-auth"
+  },
+  "exports": {
+    "./core": "./dist/core/index.js",
+    "./client": "./dist/client/index.js",
+    "./worker": "./dist/worker/index.js"
+  },
+  "devDependencies": {
+    "@kinde-oss/kinde-auth-pkce-js": "^4.3.0",
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "jose": "^6.2.3",
+    "rollup": "^4.60.4"
+  },
+  "keywords": [
+    "kinde",
+    "auth",
+    "iam"
+  ],
+  "scripts": {
+    "build:dev": "rollup -c --environment BUILD_ENV:development",
+    "build:prod": "rollup -c --environment BUILD_ENV:production",
+    "watch": "rollup -c -w --environment BUILD_ENV:development",
+    "test": "echo \"Warning: no test specified\" && exit 0"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,102 @@
+/******************************************************************************/
+
+
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import terser from '@rollup/plugin-terser';
+
+
+/******************************************************************************/
+
+
+/* The build environment that we are targeting. */
+const build_env = process.env.BUILD_ENV ?? 'development';
+
+/* Evaluates if the environment target is configured for deployment. */
+const is_production = build_env === 'production';
+
+/* Files mentioned here are not inlined into build bundles; this generally only
+ * applies to the code in the core library, which is client and worker agnostic.
+ *
+ * References to the files are kept as is, and since the output folder is kept
+ * in the same file layout as the source folders are, when the compiled code is
+ * used, it picks up the proper file automatically. */
+const internalExternal = [
+  '../core/index.js'
+];
+
+/* Set up the optimization plugins that should only be injected into the build
+ * pipeline when creating production assets. */
+const optimizationPlugins = is_production === true ? [
+  terser({
+    toplevel: true,
+    compress: {
+      passes: 2,
+      drop_console: true
+    },
+    format: {
+      comments: 'some'
+    }
+  })
+] : [];
+
+
+/******************************************************************************/
+
+
+export default [
+  /* The core module contains all code that is common to the Client and Worker;
+   * there is nothing contained in here that is either browser or worker
+   * specific. */
+  {
+    input: 'src/core/index.js',
+    output: {
+      file: 'dist/core/index.js',
+      format: 'esm'
+    },
+    plugins: [
+      resolve(),
+      commonjs(),
+      ...optimizationPlugins
+    ]
+  },
+
+  /* The client module contains all code that is intended to be used in the
+   * browser by client-side code. */
+  {
+    input: 'src/client/index.js',
+    external: internalExternal,
+    output: {
+      file: 'dist/client/index.js',
+      format: 'esm'
+    },
+    plugins: [
+      resolve({
+        browser: true
+      }),
+      commonjs(),
+      ...optimizationPlugins
+    ]
+  },
+
+  /* The worker module contains all code that is intended to be used in worker
+   * code. */
+  {
+    input: 'src/worker/index.js',
+    external: internalExternal,
+    output: {
+      file: 'dist/worker/index.js',
+      format: 'esm'
+    },
+    plugins: [
+      resolve({
+        exportConditions: ['worker', 'import']
+      }),
+      commonjs(),
+      ...optimizationPlugins
+    ]
+  }
+];
+
+
+/******************************************************************************/

package/src/client/index.js

@@ -0,0 +1,115 @@
+/******************************************************************************/
+
+
+import createKindeClient from '@kinde-oss/kinde-auth-pkce-js';
+import { extractFlags } from '../core/index.js';
+
+
+/******************************************************************************/
+
+
+/* Initializes the Kinde authentication client for browser-based Single Page
+ * Applications (SPAs) using the PKCE flow.
+ *
+ * This factory function takes the config parameters provided, instantiates the
+ * underlying Kinde SDK, and then returns a clean, simplified API surface.
+ *
+ * This abstracts away the need for the application to directly parse tokens by
+ * providing a getContext() method that fully evaluates the user's session
+ * state, roles, permissions, and feature flags.
+ *
+ * The configuration object is as would be passed to createKindeClient, and can
+ * have the following keys:
+ *   Required:
+ *     client_id:    The unique ID of the application in Kinde.
+ *     domain:       Your Kinde domain (e.g., 'https://yourdomain.kinde.com').
+ *     redirect_uri: The local URL to redirect back to after a successful login.
+ *
+ *   Optional:
+ *     logout_uri:   The local URL to redirect to after a successful logout.
+ *     audience:     The API identifier to ensure tokens are scoped to your
+ *                   specific backend.
+ *     scope:        A space-separated list of requested scopes (defaults to
+ *                   'openid profile email offline').
+ *
+ * The turn value of the call is an object that contains the following methods:
+ *   login:           (Async) Redirects to the Kinde login flow.
+ *   register:        (Async) Redirects to the Kinde registration flow.
+ *   logout:          (Async) Clears the local session and redirects to the
+ *                            Kinde logout flow.
+ *   getToken:        (Async) Returns the raw JWT access token/
+ *   isAuthenticated: (Async) Returns a boolean indicating if a valid, unexpired
+ *                            session currently exists.
+ *   getContext:      (Async) Returns the master user state object, or null if
+ *                            the user is not authenticated.
+ *
+ * Application code can call getContext() in order to obtain an object that has
+ * decoded information from the token:
+ *   profile:     An object containing the user's profile information extracted
+ *                from the ID token (e.g., id, given_name, email).
+ *   permissions: An object containing the permissions granted to the user.
+ *   roles:       A list of role objects assigned to the user within the Kinde
+ *                environment; null if there are none
+ *   featureFlag: A function that returns the value of the named feature flag,
+ *                returning the default value if the flag is not set.
+ *   flags:       A flattened dictionary of all feature flags; the featureFlag()
+ *                function accesses this.
+ */
+export async function createClientAuth(config) {
+  // Initializing the client automatically evaluates the current URL to see if
+  // the user is returning from a Kinde login redirect, parsing the token
+  // fragments out of the URL if present.
+  const kinde = await createKindeClient(config);
+
+  return {
+    // Standard authentication flow triggers. These redirect the browser to the
+    // hosted Kinde pages to handle user credentials securely.
+    login: async () => await kinde.login(),
+    register: async () => await kinde.register(),
+    logout: async () => await kinde.logout(),
+
+    // Retrieves the raw JWT access token string, which is necessary to inject
+    // into the Authorization header when making calls to our secured backend
+    // APIs.
+    getToken: async () => await kinde.getToken(),
+
+    // Quickly evaluates if the user has a valid, non-expired session token.
+    isAuthenticated: async () => await kinde.isAuthenticated(),
+
+    // Constructs and returns the master state object for the authenticated
+    // user.
+    //
+    // This function extracts all relevant claims from both the ID token and the
+    // Access token. If the user is not authenticated, it cleanly returns null
+    // to allow the application to easily route them away from secured areas
+    // as needed.
+    getContext: async () => {
+      // Not a lot to do if the user is not authenticated.
+      const isAuthenticated = await kinde.isAuthenticated();
+      if (isAuthenticated === false) {
+        return null;
+      }
+
+      // Retrieve ID Token Data; this data contains the profile information for
+      // the user.
+      const user = await kinde.getUser();
+
+      // Retrieve Access Token Data; this data contains the authorization info
+      // for the user.
+      const permissionsData = await kinde.getPermissions();
+      const rolesClaim = await kinde.getClaim('roles');
+      const flagsClaim = await kinde.getClaim('feature_flags');
+      const flagsContext = extractFlags(flagsClaim !== null ? flagsClaim.value : null);
+
+      return {
+        profile: user,
+        permissions: permissionsData,
+        roles: rolesClaim !== null ? rolesClaim.value : null,
+        ...flagsContext,
+      };
+    }
+  };
+}
+
+
+/******************************************************************************/

package/src/core/index.js

@@ -0,0 +1,54 @@
+/******************************************************************************/
+
+
+/* Extracts and flattens feature flags from the raw token payload into a simple
+ * key-value dictionary.
+ *
+ * Kinde provides feature flags as nested objects that contain the name of the
+ * flags, their values, and their types:
+ *
+ *    "feature_flags": {
+ *     "a_boolean_flag": {
+ *       "t": "b",
+ *       "v": false
+ *     },
+ *     "a_string_flag": {
+ *       "t": "s",
+ *       "v": "control"
+ *     },
+ *     "an_integer_flag": {
+ *       "t": "i",
+ *       "v": 1000
+ *     }
+ *   }
+ *
+ * The Kinde API for the client side has routines for pulling out flags, but
+ * they require you to name the type (and generate errors if you pick the wrong
+ * one.
+ *
+ * This utility flattens the structure down to just an object with the keys and
+ * values directly, such as { flag_name: 'value' }, so that application code can
+ * easily check for flags without worrying about the nested structure.
+ *
+ * The return value is an object with a flags key (which may be empty if there
+ * are no flags or an invalid object was passed in) and a featureFlag function
+ * that returns the value of a given flag, optionally giving you a default value
+ * if the flag does not exist. */
+export function extractFlags(featureFlags) {
+  const flags = {};
+
+  // If we got a flags object, pull the keys out into a new flattened object.
+  if (featureFlags !== undefined && featureFlags !== null) {
+    for (const [key, data] of Object.entries(featureFlags)) {
+      flags[key] = data.v;
+    }
+  }
+
+  return {
+    flags,
+    featureFlag: (flag, defaultValue) =>  flags[flag] === undefined ? defaultValue : flags[flag],
+  }
+}
+
+
+/******************************************************************************/

package/src/worker/index.js

@@ -0,0 +1,97 @@
+/******************************************************************************/
+
+
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { extractFlags } from '../core/index.js';
+
+
+/******************************************************************************/
+
+
+/* A global cache used to persist the JSON Web Key Set (JWKS) across multiple
+ * request invocations within the same Cloudflare Worker isolate.
+ *
+ * Fetching the public keys from Kinde on every single request would add severe
+ * latency. By declaring this outside the request handler, the Worker keeps the
+ * keys in memory as long as the isolate stays warm. */
+let jwksCache = null;
+
+
+/******************************************************************************/
+
+
+/* Parses the incoming HTTP request to extract the JWT from the Authorization
+ * header. It strictly expects the standard 'Bearer <token>' format.
+ *
+ * Returns null if the header is missing or improperly formatted. */
+export function extractBearerToken(request) {
+  const authHeader = request.headers.get('Authorization');
+  if (authHeader !== null && authHeader.startsWith('Bearer ') === true) {
+    return authHeader.split(' ')[1];
+  }
+
+  return null;
+}
+
+
+/******************************************************************************/
+
+
+/* Verifies the cryptographic signature of the provided JWT against Kinde's
+ * published public keys (JWKS) to guarantee the token was genuinely issued by
+ * Kinde and has not been tampered with or expired.
+ *
+ * If the verification is successful, the payload is decoded and used to create
+ * the exact same object that the client side library produces from the client
+ * object's getContext() function call.
+ *
+ * This allows application code to expect a uniform structure regardless of what
+ * side it is running on.
+ *
+ * The returned object will have a success key that indicates if the validation
+ * was successful or not; if not, the error field says why the validation failed
+ * for error reporting purposes; otherwise, the context key is the same value
+ * as would be returned from a call to the client side getContext() function
+ * call. */
+export async function verifyToken(token, jwksUrl, issuer) {
+  // Lazily initialize the JWKS cache on the first authentication attempt the
+  // worker handles. Subsequent requests will reuse this cached object.
+  if (jwksCache === null) {
+    jwksCache = createRemoteJWKSet(new URL(jwksUrl));
+  }
+
+  try {
+    // jwtVerify automatically checks the signature and the expiration (exp)
+    // claim. By passing the issuer, we also enforce that this token came
+    // specifically from our configured Kinde environment.
+    const { payload } = await jwtVerify(token, jwksCache, {
+      issuer: issuer
+    });
+
+    // Extract and parse the flags in the token payload.
+    const flagsContext = extractFlags(payload.feature_flags);
+
+    return {
+      success: true,
+      context: {
+        id: payload.sub,
+        permissions: payload.permissions || [],
+        rawPayload: payload,
+        ...flagsContext,
+      },
+      error: null
+    };
+  } catch (err) {
+    // Verification fails if the token is expired, the signature is invalid, or
+    // the issuer mismatches. We return a normalized failure state so the
+    // middleware can cleanly reject the request.
+    return {
+      success: false,
+      context: null,
+      error: err.message
+    };
+  }
+}
+
+
+/******************************************************************************/