@baseworks/auth 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,233 @@
+# @baseworks/auth
+
+Authentication utilities for the baseworks monorepo. Uses subpath imports so each environment only pulls in what it needs.
+
+## Subpath Imports
+
+| Import | Runtime | Contents |
+|--------|---------|----------|
+| `@baseworks/auth` | Any | token helpers, verifyHs256Jwt, verifyOidcToken, pkce, cli-auth, url-helpers |
+| `@baseworks/auth/jwt` | Node.js | HS256 JWT verification |
+| `@baseworks/auth/hono` | Node.js + Hono | `requireAuth` middleware |
+| `@baseworks/auth/oidc` | Workers / Node / Browser | OIDC token verification via JWKS |
+| `@baseworks/auth/oidc-human` | Any | OIDC → DB user resolver factory |
+| `@baseworks/auth/pkce` | Workers / Node / Browser | PKCE generation + OIDC auth URL builder |
+| `@baseworks/auth/token` | Workers / Node / Browser | hashToken, looksLikeJwt, stripBearer |
+| `@baseworks/auth/cli-auth` | Node.js CLI | Browser-based polling auth flow |
+| `@baseworks/auth/session` | Next.js (Server) | OIDC cookie session, token exchange, refresh |
+| `@baseworks/auth/edge` | Next.js (Edge/Server) | Pomerium JWT assertions + cookie fallback |
+| `@baseworks/auth/url-helpers` | Next.js | Auth/account public URL builders |
+
+---
+
+## File Reference
+
+### `jwt.ts` → `@baseworks/auth/jwt`
+**Runtime:** Node.js — uses `node:crypto`
+
+HS256 JWT verification. Used by Flect services (`org-service`, `account-service`) to verify service-to-service JWTs signed with `JWT_SECRET`.
+
+```ts
+import { verifyHs256Jwt } from '@baseworks/auth/jwt'
+
+const claims = verifyHs256Jwt(token, process.env.JWT_SECRET)
+// null → invalid signature or expired
+```
+
+---
+
+### `hono.ts` → `@baseworks/auth/hono`
+**Runtime:** Node.js + Hono — peer dep: `hono`
+
+Hono middleware. Reads `Authorization: Bearer <token>`, verifies with `jwt.ts`, sets `c.var.auth` (typed as `ServiceAuthUser`).
+
+```ts
+import { requireAuth } from '@baseworks/auth/hono'
+
+app.use('*', requireAuth)
+app.get('/me', (c) => {
+  const { userId, orgId } = c.var.auth
+})
+```
+
+> `ContextVariableMap` is augmented here — do not re-declare it in services.
+
+---
+
+### `oidc.ts` → `@baseworks/auth/oidc`
+**Runtime:** Workers / Node / Browser — dep: `jose`
+
+Provider-agnostic OIDC JWT verification. Fetches the public key from the JWKS endpoint, verifies the signature, and returns a normalised `OidcIdentity`.
+
+```ts
+import { verifyOidcToken } from '@baseworks/auth/oidc'
+
+const identity = await verifyOidcToken(bearerToken, {
+  issuer:   'https://auth.example.com',
+  audience: 'my-app',
+})
+// null → verification failed
+```
+
+JWKS endpoint: `{issuer}/oauth/v2/keys` (Zitadel-compatible).
+
+---
+
+### `oidc-human.ts` → `@baseworks/auth/oidc-human`
+**Runtime:** Any — dep: `oidc.ts`, `jose`
+
+Combines `verifyOidcToken` with a DB user upsert into a single resolver. The `findOrCreate` callback stays app-specific.
+
+```ts
+import { createOidcHumanResolver } from '@baseworks/auth/oidc-human'
+
+const resolve = createOidcHumanResolver({
+  issuer:       process.env.OIDC_ISSUER,
+  findOrCreate: async (identity) => db.users.upsert(identity),
+})
+
+const user = await resolve(bearerToken) // null → verification failed
+```
+
+Fast-fail: if the issuer doesn't match it returns null before hitting the JWKS endpoint.
+
+---
+
+### `pkce.ts` → `@baseworks/auth/pkce`
+**Runtime:** Workers / Node / Browser — dep: Web Crypto API, `@baseworks/core`
+
+PKCE (RFC 7636) `code_verifier` + `code_challenge` generation. OIDC authorization URL builder compatible with any provider (Zitadel, Auth0, Keycloak, etc.).
+
+```ts
+import { generatePkce, buildOidcAuthUrl } from '@baseworks/auth/pkce'
+
+const { verifier, challenge } = await generatePkce()
+const url = buildOidcAuthUrl({ issuer, clientId, redirectUri, challenge })
+```
+
+---
+
+### `token.ts` → `@baseworks/auth/token`
+**Runtime:** Workers / Node / Browser — dep: Web Crypto API
+
+General-purpose token helpers.
+
+```ts
+import { hashToken, looksLikeJwt, stripBearer } from '@baseworks/auth/token'
+
+const hash   = await hashToken(rawToken, 'optional-pepper') // SHA-256 hex
+const raw    = stripBearer(request.headers.get('Authorization')) // null if missing
+const isJwt  = looksLikeJwt(token) // true if 3-part dot-separated
+```
+
+---
+
+### `cli-auth.ts` → `@baseworks/auth/cli-auth`
+**Runtime:** Node.js CLI — dep: `fetch`
+
+CLI → browser auth polling flow. Used by commands like `flect login`. The user opens a URL in the browser; the CLI polls until auth completes.
+
+```ts
+import { startCliAuth, pollCliAuth } from '@baseworks/auth/cli-auth'
+
+const { state, url } = await startCliAuth('https://api.flect.run')
+console.log(`Open: ${url}`)
+const { token } = await pollCliAuth('https://api.flect.run', state)
+```
+
+---
+
+### `session.ts` → `@baseworks/auth/session`
+**Runtime:** Next.js (Server Components, Route Handlers) — dep: `next`
+
+Full OIDC PKCE session management for Next.js. Handles cookie set/clear, authorization code exchange, and token refresh. Uses `@baseworks/core` for base64url encoding and `pkce.ts` for PKCE generation.
+
+```ts
+import {
+  buildAuthorizationRedirect,
+  handleAuthorizationCallback,
+  getSessionFromCookies,
+  getServerAccessToken,
+  buildLogoutResponse,
+} from '@baseworks/auth/session'
+```
+
+Reads env vars: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (optional).
+
+---
+
+### `edge.ts` → `@baseworks/auth/edge`
+**Runtime:** Next.js (Middleware, Server Components) — dep: `next`
+
+Reads the session from two sources in priority order: **Pomerium JWT assertion headers** (`x-pomerium-jwt-assertion`) first, then **OIDC cookie** fallback. Returns an `EdgeSession`.
+
+```ts
+import { getEdgeSession } from '@baseworks/auth/edge'
+
+const session = await getEdgeSession()
+// session.provider: 'pomerium' | 'cookie' | 'anonymous'
+```
+
+---
+
+### `url-helpers.ts` → `@baseworks/auth/url-helpers`
+**Runtime:** Next.js — dep: none
+
+Reads Next.js env vars and exposes URL builder functions.
+
+```ts
+import { buildAuthLoginUrl, buildAuthLogoutUrl } from '@baseworks/auth/url-helpers'
+
+const loginUrl  = buildAuthLoginUrl('/dashboard')
+const logoutUrl = buildAuthLogoutUrl('/')
+```
+
+Env vars read: `NEXT_PUBLIC_AUTH_URL`, `NEXT_PUBLIC_ACCOUNT_URL`, `APP_PUBLIC_URL`, `NEXT_PUBLIC_SITE_URL`.
+
+---
+
+### `_internal.ts` — not exported
+Shared internal helpers. Not part of the public API.
+
+- `parseJwtPayload(token)` — splits a JWT and decodes the payload using `@baseworks/core/codec`. Used by `session.ts` and `edge.ts`.
+
+---
+
+## Internal Dependencies
+
+```
+@baseworks/core/codec
+  └── base64urlEncode / base64urlDecodeString
+        ├── pkce.ts        (PKCE verifier/challenge generation)
+        ├── session.ts     (cookie encode/decode)
+        └── _internal.ts  (parseJwtPayload)
+                └── edge.ts
+```
+
+## When to Use What
+
+```
+Service-to-service JWT verification (Hono/Node)
+  └─ @baseworks/auth/hono         →  requireAuth middleware
+
+Raw HS256 JWT verify
+  └─ @baseworks/auth/jwt          →  verifyHs256Jwt
+
+User OIDC token verification (Workers/Node)
+  └─ @baseworks/auth/oidc         →  verifyOidcToken
+
+OIDC token + DB user sync in one step
+  └─ @baseworks/auth/oidc-human   →  createOidcHumanResolver
+
+API key hashing / Bearer header parsing
+  └─ @baseworks/auth/token        →  hashToken / stripBearer
+
+Next.js OIDC login / callback / logout
+  └─ @baseworks/auth/session      →  buildAuthorizationRedirect / handleAuthorizationCallback
+
+Who is this user in Next.js Middleware?
+  └─ @baseworks/auth/edge         →  getEdgeSession
+
+CLI browser auth
+  └─ @baseworks/auth/cli-auth     →  startCliAuth / pollCliAuth
+```

package/dist/{chunk-M7EACPIB.js → chunk-34E5PYNA.js}

@@ -1,11 +1,9 @@
 // src/pkce.ts
+import { base64urlEncode } from "@baseworks/core";
 async function generatePkce() {
-  const array = new Uint8Array(32);
-  crypto.getRandomValues(array);
-  const verifier = base64url(array);
-  const encoded = new TextEncoder().encode(verifier);
-  const digest = await crypto.subtle.digest("SHA-256", encoded);
-  const challenge = base64url(new Uint8Array(digest));
+  const verifier = base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  const challenge = base64urlEncode(new Uint8Array(digest));
   return { verifier, challenge, method: "S256" };
 }
 function buildOidcAuthUrl(config) {
@@ -23,9 +21,6 @@ function buildOidcAuthUrl(config) {
   if (config.prompt) params.set("prompt", config.prompt);
   return `${issuer}/oauth/v2/authorize?${params.toString()}`;
 }
-function base64url(buf) {
-  return btoa(Array.from(buf, (b) => String.fromCharCode(b)).join("")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}
 
 export {
   generatePkce,

package/dist/{chunk-VUB4GTMI.js → chunk-NBKMWUCN.js}

@@ -1,3 +1,6 @@
+import {
+  generatePkce
+} from "./chunk-34E5PYNA.js";
 import {
   getAuthPublicUrl,
   normalizeUrlLike
@@ -6,6 +9,7 @@ import {
 // src/session.ts
 import { cookies } from "next/headers";
 import { NextResponse } from "next/server";
+import { base64urlEncode, base64urlDecodeString } from "@baseworks/core";
 var oidcCookies = {
   codeVerifier: "oidc_code_verifier",
   state: "oidc_state",
@@ -56,26 +60,8 @@ function resolvePublicRedirect(target, request) {
   if (publicSiteUrl) return new URL(target, publicSiteUrl);
   return new URL(target, request.url);
 }
-function base64UrlEncode(input) {
-  const buffer = typeof input === "string" ? Buffer.from(input, "utf8") : Buffer.from(input instanceof Uint8Array ? input : new Uint8Array(input));
-  return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function base64UrlDecode(input) {
-  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
-  const remainder = padded.length % 4;
-  const normalized = remainder === 0 ? padded : `${padded}${"=".repeat(4 - remainder)}`;
-  return Buffer.from(normalized, "base64").toString("utf8");
-}
-function sha256(input) {
-  return crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
-}
 function randomString() {
-  return base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
-}
-async function createPkcePair() {
-  const verifier = randomString();
-  const challenge = base64UrlEncode(await sha256(verifier));
-  return { challenge, verifier };
+  return base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
 }
 async function discoverOidc() {
   const issuer = getIssuer();
@@ -84,26 +70,26 @@ async function discoverOidc() {
   return await response.json();
 }
 function parseJwtPayload(token) {
-  const [, payload = ""] = token.split(".");
-  return JSON.parse(base64UrlDecode(payload));
+  const part = token.split(".")[1] ?? "";
+  return JSON.parse(base64urlDecodeString(part));
 }
 function encodeSessionCookie(session) {
-  return base64UrlEncode(JSON.stringify(session));
+  return base64urlEncode(new TextEncoder().encode(JSON.stringify(session)));
 }
 function parseSessionCookie(value) {
   try {
-    const session = JSON.parse(base64UrlDecode(value));
+    const session = JSON.parse(base64urlDecodeString(value));
     return session.isAuthenticated ? session : null;
   } catch {
     return null;
   }
 }
 function encodeTransactionCookie(transaction) {
-  return base64UrlEncode(JSON.stringify(transaction));
+  return base64urlEncode(new TextEncoder().encode(JSON.stringify(transaction)));
 }
 function parseTransactionCookie(value) {
   try {
-    const transaction = JSON.parse(base64UrlDecode(value));
+    const transaction = JSON.parse(base64urlDecodeString(value));
     if (!transaction.codeVerifier || !transaction.returnTo) return null;
     return transaction;
   } catch {
@@ -142,7 +128,7 @@ function getRedirectUri(request) {
 }
 function appendClientAuthentication(headers, params, clientId, clientSecret) {
   if (clientSecret) {
-    const basic = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    const basic = btoa(`${clientId}:${clientSecret}`);
     headers.set("authorization", `Basic ${basic}`);
     return;
   }
@@ -235,7 +221,7 @@ function clearTransientCookies(response, request) {
 async function buildAuthorizationRedirect(request) {
   const discovery = await discoverOidc();
   const clientId = getClientId();
-  const { challenge, verifier } = await createPkcePair();
+  const { challenge, verifier } = await generatePkce();
   const nonce = randomString();
   const state = randomString();
   const redirectUri = getRedirectUri(request);

package/dist/chunk-TXDBQMTY.js

@@ -0,0 +1,23 @@
+// src/jwt.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyHs256Jwt(token, secret) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [header, payload, sig] = parts;
+  const expected = createHmac("sha256", secret).update(`${header}.${payload}`).digest("base64url");
+  const sigBuf = Buffer.from(sig, "base64url");
+  const expBuf = Buffer.from(expected, "base64url");
+  if (sigBuf.length !== expBuf.length) return null;
+  if (!timingSafeEqual(sigBuf, expBuf)) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString());
+    if (claims.exp && claims.exp < Math.floor(Date.now() / 1e3)) return null;
+    return claims;
+  } catch {
+    return null;
+  }
+}
+
+export {
+  verifyHs256Jwt
+};

package/dist/edge.js

@@ -1,6 +1,7 @@
 import {
   getSessionFromCookies
-} from "./chunk-VUB4GTMI.js";
+} from "./chunk-NBKMWUCN.js";
+import "./chunk-34E5PYNA.js";
 import {
   buildPublicUrl,
   normalizeUrlLike
@@ -9,6 +10,20 @@ import {
 // src/edge.ts
 import { headers } from "next/headers";
 import { redirect } from "next/navigation";
+
+// src/_internal.ts
+import { base64urlDecodeString } from "@baseworks/core";
+function parseJwtPayload(token) {
+  try {
+    const part = token.split(".")[1];
+    if (!part) return null;
+    return JSON.parse(base64urlDecodeString(part));
+  } catch {
+    return null;
+  }
+}
+
+// src/edge.ts
 function firstHeader(headerStore, names) {
   for (const name of names) {
     const value = headerStore.get(name);
@@ -16,20 +31,6 @@ function firstHeader(headerStore, names) {
   }
   return void 0;
 }
-function decodeBase64Url(value) {
-  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
-  return Buffer.from(padded, "base64").toString("utf8");
-}
-function parseJwtPayload(token) {
-  try {
-    const [, payload] = token.split(".");
-    if (!payload) return null;
-    return JSON.parse(decodeBase64Url(payload));
-  } catch {
-    return null;
-  }
-}
 function stringClaim(claims, keys) {
   for (const key of keys) {
     const value = claims[key];

package/dist/hono.d.ts

@@ -0,0 +1,26 @@
+import * as hono from 'hono';
+import { Context, Next } from 'hono';
+
+interface ServiceAuthUser {
+    userId: string;
+    orgId?: string;
+    role?: string;
+    tokenType: 'user' | 'service';
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        auth: ServiceAuthUser;
+    }
+}
+/**
+ * Hono middleware — verifies HS256 JWT from Authorization: Bearer header.
+ * Reads JWT_SECRET from process.env.
+ * Sets c.var.auth on success.
+ */
+declare function requireAuth(c: Context, next: Next): Promise<void | (Response & hono.TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & hono.TypedResponse<{
+    error: string;
+}, 500, "json">)>;
+
+export { type ServiceAuthUser, requireAuth };

package/dist/hono.js

@@ -0,0 +1,24 @@
+import {
+  verifyHs256Jwt
+} from "./chunk-TXDBQMTY.js";
+
+// src/hono.ts
+async function requireAuth(c, next) {
+  const header = c.req.header("Authorization");
+  if (!header?.startsWith("Bearer ")) return c.json({ error: "Unauthorized" }, 401);
+  const token = header.slice(7);
+  const secret = process.env["JWT_SECRET"];
+  if (!secret) return c.json({ error: "JWT_SECRET not configured" }, 500);
+  const claims = verifyHs256Jwt(token, secret);
+  if (!claims) return c.json({ error: "Unauthorized" }, 401);
+  c.set("auth", {
+    userId: String(claims["sub"] ?? ""),
+    orgId: claims["org_id"],
+    role: claims["role"],
+    tokenType: claims["type"] === "service" ? "service" : "user"
+  });
+  return next();
+}
+export {
+  requireAuth
+};

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { OidcHumanResolverConfig, createOidcHumanResolver } from './oidc-human.j
 export { OidcAuthUrlConfig, PkceChallenge, buildOidcAuthUrl, generatePkce } from './pkce.js';
 export { CliAuthResult, CliAuthStart, PollOptions, pollCliAuth, startCliAuth } from './cli-auth.js';
 export { hashToken, looksLikeJwt, stripBearer } from './token.js';
+export { JwtClaims, verifyHs256Jwt } from './jwt.js';
 export { buildAccountProfileUrl, buildAuthLoginUrl, buildAuthLogoutUrl, buildPublicUrl, getAccountPublicUrl, getAppBasePath, getAuthPublicUrl, getPublicSiteUrl, normalizeUrlLike } from './url-helpers.js';
-export { ZitadelClaims, ZitadelConfig, ZitadelIdentity, verifyZitadelToken } from './zitadel.js';

package/dist/index.js

@@ -1,16 +1,12 @@
 import {
-  verifyZitadelToken
-} from "./chunk-BMPRMOI7.js";
+  verifyHs256Jwt
+} from "./chunk-TXDBQMTY.js";
 import {
   createOidcHumanResolver
 } from "./chunk-6TUNNS2B.js";
 import {
   verifyOidcToken
 } from "./chunk-BL74TFCV.js";
-import {
-  buildOidcAuthUrl,
-  generatePkce
-} from "./chunk-M7EACPIB.js";
 import {
   pollCliAuth,
   startCliAuth
@@ -20,6 +16,10 @@ import {
   looksLikeJwt,
   stripBearer
 } from "./chunk-VBIQJKUU.js";
+import {
+  buildOidcAuthUrl,
+  generatePkce
+} from "./chunk-34E5PYNA.js";
 import {
   buildAccountProfileUrl,
   buildAuthLoginUrl,
@@ -49,6 +49,6 @@ export {
   pollCliAuth,
   startCliAuth,
   stripBearer,
-  verifyOidcToken,
-  verifyZitadelToken
+  verifyHs256Jwt,
+  verifyOidcToken
 };

package/dist/jwt.d.ts

@@ -0,0 +1,17 @@
+interface JwtClaims {
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    org_id?: string;
+    role?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * Verify an HS256 JWT using Node.js crypto.
+ * Returns decoded claims on success, null on any failure.
+ * Runtime: Node.js only (uses `crypto` module).
+ */
+declare function verifyHs256Jwt(token: string, secret: string): JwtClaims | null;
+
+export { type JwtClaims, verifyHs256Jwt };

package/dist/jwt.js

@@ -0,0 +1,6 @@
+import {
+  verifyHs256Jwt
+} from "./chunk-TXDBQMTY.js";
+export {
+  verifyHs256Jwt
+};

package/dist/pkce.d.ts

@@ -1,7 +1,3 @@
-/**
- * PKCE (Proof Key for Code Exchange) utilities — RFC 7636.
- * Runtime-agnostic: Workers, Node 20+, browser (Web Crypto API).
- */
 interface PkceChallenge {
     verifier: string;
     challenge: string;

package/dist/pkce.js

@@ -1,7 +1,7 @@
 import {
   buildOidcAuthUrl,
   generatePkce
-} from "./chunk-M7EACPIB.js";
+} from "./chunk-34E5PYNA.js";
 export {
   buildOidcAuthUrl,
   generatePkce

package/dist/session.js

@@ -9,7 +9,8 @@ import {
   handleAuthorizationCallback,
   hasServerOidcSession,
   oidcCookies
-} from "./chunk-VUB4GTMI.js";
+} from "./chunk-NBKMWUCN.js";
+import "./chunk-34E5PYNA.js";
 import "./chunk-3NJASEF4.js";
 export {
   buildAuthorizationRedirect,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baseworks/auth",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -12,7 +12,8 @@
     "./session": "./dist/session.js",
     "./url-helpers": "./dist/url-helpers.js",
     "./edge": "./dist/edge.js",
-    "./zitadel": "./dist/zitadel.js"
+    "./jwt": "./dist/jwt.js",
+    "./hono": "./dist/hono.js"
   },
   "files": [
     "dist",
@@ -23,20 +24,25 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@baseworks/core": "^0.2.0",
+    "@baseworks/core": "workspace:*",
     "jose": "^6.2.3"
   },
   "peerDependencies": {
+    "hono": ">=4.0.0",
     "next": ">=15.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@baseworks/tsconfig": "workspace:*",
     "@types/node": "^26.0.1",
+    "hono": "^4.12.27",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0"
   }

package/src/_internal.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared internal utilities — not exported from package public API.
+ */
+import { base64urlDecodeString } from '@baseworks/core'
+
+export function parseJwtPayload(token: string): Record<string, unknown> | null {
+  try {
+    const part = token.split('.')[1]
+    if (!part) return null
+    return JSON.parse(base64urlDecodeString(part)) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}

package/src/edge.ts

@@ -5,6 +5,7 @@ import { headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { getSessionFromCookies, type OidcSession } from "./session";
 import { buildPublicUrl, normalizeUrlLike } from "./url-helpers";
+import { parseJwtPayload } from "./_internal.js";
 
 export type EdgeAuthProvider = "anonymous" | "cookie" | "pomerium";
 
@@ -24,22 +25,6 @@ function firstHeader(headerStore: Headers, names: string[]) {
   return undefined;
 }
 
-function decodeBase64Url(value: string) {
-  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
-  return Buffer.from(padded, "base64").toString("utf8");
-}
-
-function parseJwtPayload(token: string): Record<string, unknown> | null {
-  try {
-    const [, payload] = token.split(".");
-    if (!payload) return null;
-    return JSON.parse(decodeBase64Url(payload)) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-}
-
 function stringClaim(claims: Record<string, unknown>, keys: string[]) {
   for (const key of keys) {
     const value = claims[key];

package/src/hono.ts

@@ -0,0 +1,40 @@
+import type { Context, Next } from 'hono'
+import { verifyHs256Jwt } from './jwt.js'
+
+export interface ServiceAuthUser {
+  userId:    string
+  orgId?:    string
+  role?:     string
+  tokenType: 'user' | 'service'
+}
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    auth: ServiceAuthUser
+  }
+}
+
+/**
+ * Hono middleware — verifies HS256 JWT from Authorization: Bearer header.
+ * Reads JWT_SECRET from process.env.
+ * Sets c.var.auth on success.
+ */
+export async function requireAuth(c: Context, next: Next) {
+  const header = c.req.header('Authorization')
+  if (!header?.startsWith('Bearer ')) return c.json({ error: 'Unauthorized' }, 401)
+
+  const token  = header.slice(7)
+  const secret = process.env['JWT_SECRET']
+  if (!secret) return c.json({ error: 'JWT_SECRET not configured' }, 500)
+
+  const claims = verifyHs256Jwt(token, secret)
+  if (!claims) return c.json({ error: 'Unauthorized' }, 401)
+
+  c.set('auth', {
+    userId:    String(claims['sub'] ?? ''),
+    orgId:     claims['org_id'] as string | undefined,
+    role:      claims['role'] as string | undefined,
+    tokenType: claims['type'] === 'service' ? 'service' : 'user',
+  })
+  return next()
+}

package/src/index.ts

@@ -17,6 +17,10 @@ export type { CliAuthStart, CliAuthResult, PollOptions } from './cli-auth';
 // Token utilities
 export { hashToken, looksLikeJwt, stripBearer } from './token';
 
+// HS256 JWT verification (Node.js)
+export { verifyHs256Jwt } from './jwt';
+export type { JwtClaims } from './jwt';
+
 // URL helpers (auth/account public URLs, login/logout URL builders)
 export {
   normalizeUrlLike,
@@ -34,6 +38,3 @@ export {
 // Use subpath imports: @baseworks/auth/session, @baseworks/auth/edge
 // This keeps the main index Worker-safe (no next/server dependency).
 
-// Legacy re-export — kept for backward compatibility, prefer verifyOidcToken
-export { verifyZitadelToken } from './zitadel';
-export type { ZitadelConfig, ZitadelIdentity, ZitadelClaims } from './zitadel';

package/src/jwt.ts

@@ -0,0 +1,39 @@
+import { createHmac, timingSafeEqual } from 'crypto'
+
+export interface JwtClaims {
+  sub?:    string
+  exp?:    number
+  iat?:    number
+  org_id?: string
+  role?:   string
+  type?:   string
+  [key: string]: unknown
+}
+
+/**
+ * Verify an HS256 JWT using Node.js crypto.
+ * Returns decoded claims on success, null on any failure.
+ * Runtime: Node.js only (uses `crypto` module).
+ */
+export function verifyHs256Jwt(token: string, secret: string): JwtClaims | null {
+  const parts = token.split('.')
+  if (parts.length !== 3) return null
+
+  const [header, payload, sig] = parts as [string, string, string]
+  const expected = createHmac('sha256', secret)
+    .update(`${header}.${payload}`)
+    .digest('base64url')
+
+  const sigBuf = Buffer.from(sig, 'base64url')
+  const expBuf = Buffer.from(expected, 'base64url')
+  if (sigBuf.length !== expBuf.length) return null
+  if (!timingSafeEqual(sigBuf, expBuf)) return null
+
+  try {
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString()) as JwtClaims
+    if (claims.exp && claims.exp < Math.floor(Date.now() / 1000)) return null
+    return claims
+  } catch {
+    return null
+  }
+}

package/src/pkce.ts

@@ -2,6 +2,7 @@
  * PKCE (Proof Key for Code Exchange) utilities — RFC 7636.
  * Runtime-agnostic: Workers, Node 20+, browser (Web Crypto API).
  */
+import { base64urlEncode } from '@baseworks/core'
 
 export interface PkceChallenge {
   verifier:  string;
@@ -29,14 +30,9 @@ export interface OidcAuthUrlConfig {
 
 /** Generate a PKCE code_verifier + S256 code_challenge pair. */
 export async function generatePkce(): Promise<PkceChallenge> {
-  const array    = new Uint8Array(32);
-  crypto.getRandomValues(array);
-  const verifier = base64url(array);
-
-  const encoded   = new TextEncoder().encode(verifier);
-  const digest    = await crypto.subtle.digest('SHA-256', encoded);
-  const challenge = base64url(new Uint8Array(digest));
-
+  const verifier  = base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
+  const digest    = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+  const challenge = base64urlEncode(new Uint8Array(digest));
   return { verifier, challenge, method: 'S256' };
 }
 
@@ -49,12 +45,12 @@ export function buildOidcAuthUrl(config: OidcAuthUrlConfig): string {
   const scopes = (config.scopes ?? ['openid', 'email', 'profile']).join(' ');
 
   const params = new URLSearchParams({
-    client_id:              config.clientId,
-    redirect_uri:           config.redirectUri,
-    response_type:          'code',
-    scope:                  scopes,
-    code_challenge:         config.challenge,
-    code_challenge_method:  'S256',
+    client_id:             config.clientId,
+    redirect_uri:          config.redirectUri,
+    response_type:         'code',
+    scope:                 scopes,
+    code_challenge:        config.challenge,
+    code_challenge_method: 'S256',
   });
 
   if (config.state)  params.set('state',  config.state);
@@ -62,12 +58,3 @@ export function buildOidcAuthUrl(config: OidcAuthUrlConfig): string {
 
   return `${issuer}/oauth/v2/authorize?${params.toString()}`;
 }
-
-// ─── helpers ────────────────────────────────────────────────────────────────
-
-function base64url(buf: Uint8Array): string {
-  return btoa(Array.from(buf, (b) => String.fromCharCode(b)).join(''))
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-}

package/src/session.ts

@@ -4,7 +4,9 @@
 import { cookies } from "next/headers";
 import type { NextRequest } from "next/server";
 import { NextResponse } from "next/server";
+import { base64urlEncode, base64urlDecodeString } from "@baseworks/core";
 import { getAuthPublicUrl, normalizeUrlLike } from "./url-helpers";
+import { generatePkce } from "./pkce.js";
 
 type DiscoveryDocument = {
   authorization_endpoint: string;
@@ -117,33 +119,8 @@ function resolvePublicRedirect(target: string, request: NextRequest) {
   return new URL(target, request.url);
 }
 
-function base64UrlEncode(input: ArrayBuffer | Uint8Array | string) {
-  const buffer =
-    typeof input === "string"
-      ? Buffer.from(input, "utf8")
-      : Buffer.from(input instanceof Uint8Array ? input : new Uint8Array(input));
-  return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-
-function base64UrlDecode(input: string) {
-  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
-  const remainder = padded.length % 4;
-  const normalized = remainder === 0 ? padded : `${padded}${"=".repeat(4 - remainder)}`;
-  return Buffer.from(normalized, "base64").toString("utf8");
-}
-
-function sha256(input: string) {
-  return crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
-}
-
 function randomString() {
-  return base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
-}
-
-async function createPkcePair() {
-  const verifier = randomString();
-  const challenge = base64UrlEncode(await sha256(verifier));
-  return { challenge, verifier };
+  return base64urlEncode(crypto.getRandomValues(new Uint8Array(32)));
 }
 
 async function discoverOidc() {
@@ -154,17 +131,17 @@ async function discoverOidc() {
 }
 
 function parseJwtPayload(token: string): JwtPayload {
-  const [, payload = ""] = token.split(".");
-  return JSON.parse(base64UrlDecode(payload)) as JwtPayload;
+  const part = token.split(".")[1] ?? "";
+  return JSON.parse(base64urlDecodeString(part)) as JwtPayload;
 }
 
 function encodeSessionCookie(session: OidcSession) {
-  return base64UrlEncode(JSON.stringify(session));
+  return base64urlEncode(new TextEncoder().encode(JSON.stringify(session)));
 }
 
 function parseSessionCookie(value: string): OidcSession | null {
   try {
-    const session = JSON.parse(base64UrlDecode(value)) as OidcSession;
+    const session = JSON.parse(base64urlDecodeString(value)) as OidcSession;
     return session.isAuthenticated ? session : null;
   } catch {
     return null;
@@ -172,12 +149,12 @@ function parseSessionCookie(value: string): OidcSession | null {
 }
 
 function encodeTransactionCookie(transaction: OidcTransaction) {
-  return base64UrlEncode(JSON.stringify(transaction));
+  return base64urlEncode(new TextEncoder().encode(JSON.stringify(transaction)));
 }
 
 function parseTransactionCookie(value: string): OidcTransaction | null {
   try {
-    const transaction = JSON.parse(base64UrlDecode(value)) as OidcTransaction;
+    const transaction = JSON.parse(base64urlDecodeString(value)) as OidcTransaction;
     if (!transaction.codeVerifier || !transaction.returnTo) return null;
     return transaction;
   } catch {
@@ -232,7 +209,7 @@ function appendClientAuthentication(
   clientSecret?: string,
 ) {
   if (clientSecret) {
-    const basic = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    const basic = btoa(`${clientId}:${clientSecret}`);
     headers.set("authorization", `Basic ${basic}`);
     return;
   }
@@ -347,7 +324,7 @@ function clearTransientCookies(response: NextResponse, request: NextRequest) {
 export async function buildAuthorizationRedirect(request: NextRequest) {
   const discovery = await discoverOidc();
   const clientId = getClientId();
-  const { challenge, verifier } = await createPkcePair();
+  const { challenge, verifier } = await generatePkce();
   const nonce = randomString();
   const state = randomString();
   const redirectUri = getRedirectUri(request);

package/dist/chunk-BMPRMOI7.js

@@ -1,23 +0,0 @@
-// src/zitadel.ts
-import { createRemoteJWKSet, jwtVerify } from "jose";
-function withoutTrailingSlash(v) {
-  return v.replace(/\/+$/, "");
-}
-async function verifyZitadelToken(token, config) {
-  const issuer = withoutTrailingSlash(config.issuer);
-  const jwks = createRemoteJWKSet(new URL(`${issuer}/oauth/v2/keys`));
-  const opts = config.audience ? { issuer, audience: config.audience } : { issuer };
-  const result = await jwtVerify(token, jwks, opts).catch(() => null);
-  if (!result) return null;
-  const payload = result.payload;
-  const subject = String(payload.sub ?? "");
-  if (!subject) return null;
-  const email = String(payload.email ?? payload.preferred_username ?? `${subject}@zitadel.local`);
-  const name = String(payload.name ?? payload.preferred_username ?? email);
-  const picture = payload.picture ? String(payload.picture) : void 0;
-  return { subject, issuer, email, name, picture };
-}
-
-export {
-  verifyZitadelToken
-};

package/dist/zitadel.d.ts

@@ -1,28 +0,0 @@
-interface ZitadelConfig {
-    issuer: string;
-    audience?: string;
-}
-interface ZitadelClaims {
-    sub: string;
-    email?: string;
-    preferred_username?: string;
-    name?: string;
-    picture?: string;
-    exp?: number;
-    iss?: string;
-    aud?: string | string[];
-}
-interface ZitadelIdentity {
-    subject: string;
-    issuer: string;
-    email: string;
-    name: string;
-    picture?: string;
-}
-/**
- * Verify a Zitadel JWT and return the identity.
- * Returns null on any verification failure — never throws to the caller.
- */
-declare function verifyZitadelToken(token: string, config: ZitadelConfig): Promise<ZitadelIdentity | null>;
-
-export { type ZitadelClaims, type ZitadelConfig, type ZitadelIdentity, verifyZitadelToken };

package/dist/zitadel.js

@@ -1,6 +0,0 @@
-import {
-  verifyZitadelToken
-} from "./chunk-BMPRMOI7.js";
-export {
-  verifyZitadelToken
-};

package/src/zitadel.ts

@@ -1,56 +0,0 @@
-import { createRemoteJWKSet, jwtVerify } from 'jose';
-
-export interface ZitadelConfig {
-  issuer:    string;
-  audience?: string;
-}
-
-export interface ZitadelClaims {
-  sub:                 string;
-  email?:              string;
-  preferred_username?: string;
-  name?:               string;
-  picture?:            string;
-  exp?:                number;
-  iss?:                string;
-  aud?:                string | string[];
-}
-
-// Matches OidcIdentity in @baseworks/account — intentionally compatible.
-export interface ZitadelIdentity {
-  subject:  string;
-  issuer:   string;   // normalised, no trailing slash
-  email:    string;
-  name:     string;
-  picture?: string;
-}
-
-function withoutTrailingSlash(v: string): string {
-  return v.replace(/\/+$/, '');
-}
-
-/**
- * Verify a Zitadel JWT and return the identity.
- * Returns null on any verification failure — never throws to the caller.
- */
-export async function verifyZitadelToken(
-  token: string,
-  config: ZitadelConfig,
-): Promise<ZitadelIdentity | null> {
-  const issuer = withoutTrailingSlash(config.issuer);
-  const jwks   = createRemoteJWKSet(new URL(`${issuer}/oauth/v2/keys`));
-  const opts   = config.audience ? { issuer, audience: config.audience } : { issuer };
-
-  const result = await jwtVerify(token, jwks, opts).catch(() => null);
-  if (!result) return null;
-
-  const payload = result.payload as ZitadelClaims;
-  const subject = String(payload.sub ?? '');
-  if (!subject) return null;
-
-  const email   = String(payload.email ?? payload.preferred_username ?? `${subject}@zitadel.local`);
-  const name    = String(payload.name  ?? payload.preferred_username ?? email);
-  const picture = payload.picture ? String(payload.picture) : undefined;
-
-  return { subject, issuer, email, name, picture };
-}