@baseworks/auth 0.2.0

package/src/edge.ts

@@ -0,0 +1,189 @@
+// Edge/server session: Pomerium JWT assertion headers + OIDC cookie fallback.
+// Requires: next/headers (peer dep: next).
+
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { getSessionFromCookies, type OidcSession } from "./session";
+import { buildPublicUrl, normalizeUrlLike } from "./url-helpers";
+
+export type EdgeAuthProvider = "anonymous" | "cookie" | "pomerium";
+
+export type EdgeSession = OidcSession & {
+  groups?: string[];
+  provider: EdgeAuthProvider;
+  rawClaims?: Record<string, unknown>;
+  role?: string;
+  username?: string;
+};
+
+function firstHeader(headerStore: Headers, names: string[]) {
+  for (const name of names) {
+    const value = headerStore.get(name);
+    if (value) return value;
+  }
+  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];
+    if (typeof value === "string" && value.trim()) return value;
+    if (Array.isArray(value)) {
+      const first = value.find((item) => typeof item === "string" && item.trim());
+      if (first) return first as string;
+    }
+  }
+  return undefined;
+}
+
+function parseHeaderClaim(value: string | undefined) {
+  if (!value) return undefined;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (typeof parsed === "string" && parsed.trim()) return parsed;
+    if (Array.isArray(parsed)) {
+      const first = parsed.find((item) => typeof item === "string" && item.trim());
+      if (first) return first as string;
+    }
+  } catch {
+    // Pomerium may forward plain header values depending on configuration.
+  }
+  return value.trim() || undefined;
+}
+
+function stringHeaderClaim(headerStore: Headers, names: string[]) {
+  for (const name of names) {
+    const value = parseHeaderClaim(headerStore.get(name) ?? undefined);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function stringArrayClaim(claims: Record<string, unknown>, keys: string[]) {
+  for (const key of keys) {
+    const value = claims[key];
+    if (typeof value === "string" && value.trim()) return [value];
+    if (Array.isArray(value)) {
+      const strings = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
+      if (strings.length) return strings;
+    }
+  }
+  return undefined;
+}
+
+function stringArrayHeaderClaim(headerStore: Headers, names: string[]) {
+  for (const name of names) {
+    const raw = headerStore.get(name);
+    if (!raw) continue;
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (typeof parsed === "string" && parsed.trim()) return [parsed];
+      if (Array.isArray(parsed)) {
+        const strings = parsed.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
+        if (strings.length) return strings;
+      }
+    } catch {
+      const values = raw.split(",").map((v) => v.trim()).filter(Boolean);
+      if (values.length) return values;
+    }
+  }
+  return undefined;
+}
+
+function parsePomeriumSession(headerStore: Headers): EdgeSession | null {
+  const assertion = firstHeader(headerStore, ["x-pomerium-jwt-assertion", "x-pomerium-jwt"]);
+  const claims = assertion ? parseJwtPayload(assertion) : {};
+
+  const email =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-email", "x-forwarded-email"]) ??
+    stringClaim(claims ?? {}, ["email"]);
+  const subject =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-sub", "x-pomerium-claim-user", "x-user-id"]) ??
+    stringClaim(claims ?? {}, ["sub", "user", "id"]);
+  const name =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-name", "x-forwarded-user"]) ??
+    stringClaim(claims ?? {}, ["name", "preferred_username"]);
+  const pictureUrl =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-picture"]) ??
+    stringClaim(claims ?? {}, ["picture"]);
+  const username =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-username", "x-pomerium-claim-preferred-username"]) ??
+    stringClaim(claims ?? {}, ["username", "preferred_username", "user"]);
+  const groups =
+    stringArrayHeaderClaim(headerStore, ["x-pomerium-claim-groups", "x-pomerium-claim-roles"]) ??
+    stringArrayClaim(claims ?? {}, ["groups", "roles"]);
+  const role =
+    stringHeaderClaim(headerStore, ["x-pomerium-claim-role"]) ??
+    stringClaim(claims ?? {}, ["role"]);
+
+  if (!email && !subject && !name) return null;
+
+  return {
+    email,
+    expiresAt: Number.MAX_SAFE_INTEGER,
+    groups,
+    isAuthenticated: true,
+    name,
+    pictureUrl,
+    provider: "pomerium",
+    rawClaims: claims ?? undefined,
+    role,
+    subject: subject ?? email,
+    username,
+  };
+}
+
+export async function getEdgeSession(): Promise<EdgeSession> {
+  const headerStore = await headers();
+  const pomerium = parsePomeriumSession(headerStore);
+  if (pomerium) return pomerium;
+
+  const cookieSession = await getSessionFromCookies();
+  if (cookieSession.isAuthenticated) {
+    return { ...cookieSession, provider: "cookie" };
+  }
+
+  return { expiresAt: 0, isAuthenticated: false, provider: "anonymous" };
+}
+
+export function getPomeriumAuthenticateUrl(redirectTo: string, origin?: string) {
+  const appUrl = origin ?? process.env.APP_PUBLIC_URL ?? process.env.NEXT_PUBLIC_SITE_URL;
+  if (!appUrl) return null;
+  const url = new URL(
+    process.env.POMERIUM_LOGIN_PATH ?? "/auth/edge/login",
+    `${normalizeUrlLike(appUrl)}/`,
+  );
+  url.searchParams.set("pomerium_redirect_uri", buildPublicUrl(redirectTo, origin));
+  return url.toString();
+}
+
+export function handleEdgeLogin(request: Request) {
+  const url = new URL(request.url);
+  const redirectTo = url.searchParams.get("pomerium_redirect_uri") ?? "/";
+  redirect(redirectTo);
+}
+
+export function getPomeriumSignOutUrl(redirectTo: string, origin?: string) {
+  const authUrl =
+    process.env.POMERIUM_AUTHENTICATE_URL ?? process.env.POMERIUM_AUTH_URL ?? origin;
+  if (!authUrl) return null;
+  const url = new URL("/.pomerium/sign_out", `${normalizeUrlLike(authUrl)}/`);
+  url.searchParams.set("pomerium_redirect_uri", buildPublicUrl(redirectTo, origin));
+  return url.toString();
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// OIDC verification (provider-agnostic)
+export { verifyOidcToken } from './oidc';
+export type { OidcVerifyConfig, OidcIdentity, OidcClaims } from './oidc';
+
+// Shared OIDC → HumanContext resolver (DB-agnostic)
+export { createOidcHumanResolver } from './oidc-human';
+export type { OidcHumanResolverConfig } from './oidc-human';
+
+// PKCE + authorization URL builder
+export { generatePkce, buildOidcAuthUrl } from './pkce';
+export type { PkceChallenge, OidcAuthUrlConfig } from './pkce';
+
+// CLI polling flow
+export { startCliAuth, pollCliAuth } from './cli-auth';
+export type { CliAuthStart, CliAuthResult, PollOptions } from './cli-auth';
+
+// Token utilities
+export { hashToken, looksLikeJwt, stripBearer } from './token';
+
+// URL helpers (auth/account public URLs, login/logout URL builders)
+export {
+  normalizeUrlLike,
+  getAuthPublicUrl,
+  getAccountPublicUrl,
+  getAppBasePath,
+  getPublicSiteUrl,
+  buildPublicUrl,
+  buildAuthLoginUrl,
+  buildAuthLogoutUrl,
+  buildAccountProfileUrl,
+} from './url-helpers';
+
+// Next.js session + edge exports are intentionally NOT re-exported here.
+// 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/oidc-human.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared OIDC → HumanContext resolver.
+ *
+ * Handles: JWT detection, issuer check, signature verification.
+ * DB lookup / user creation is delegated to `findOrCreate` — kept app-specific.
+ *
+ * Usage:
+ *   const resolve = createOidcHumanResolver({
+ *     issuer:       env.OIDC_ISSUER,
+ *     audience:     env.OIDC_AUDIENCE,
+ *     findOrCreate: async (identity) => { /* DB upsert *\/ },
+ *   })
+ *   const ctx = await resolve(bearerToken)
+ */
+
+import { decodeJwt }        from 'jose';
+import { verifyOidcToken }  from './oidc.js';
+import type { OidcIdentity } from './oidc.js';
+
+export type { OidcIdentity };
+
+export interface OidcHumanResolverConfig<T> {
+  /** OIDC issuer URL — e.g. https://nesskey.com */
+  issuer: string;
+  /** Optional audience restriction */
+  audience?: string;
+  /**
+   * Called after successful OIDC verification.
+   * Return the app's HumanContext or null to reject.
+   * Responsible for DB lookup / upsert.
+   * rawToken is passed so implementations can call userinfo if needed.
+   */
+  findOrCreate: (identity: OidcIdentity, rawToken: string) => Promise<T | null>;
+}
+
+/**
+ * Returns a resolver function `(token: string) => Promise<T | null>`.
+ * Call it with a raw Bearer token (JWT form). Returns null if:
+ *   - token is not a JWT
+ *   - issuer doesn't match
+ *   - signature invalid / expired
+ *   - findOrCreate returns null
+ */
+export function createOidcHumanResolver<T>(
+  config: OidcHumanResolverConfig<T>,
+): (token: string) => Promise<T | null> {
+  const issuer = config.issuer.replace(/\/+$/, '');
+
+  return async (token: string): Promise<T | null> => {
+    // Fast-fail: decode without verify to check issuer
+    let iss: string | undefined;
+    try { iss = (decodeJwt(token) as { iss?: string }).iss; } catch { return null; }
+    if (!iss || !iss.startsWith(issuer)) return null;
+
+    const identity = await verifyOidcToken(token, { issuer, audience: config.audience });
+    if (!identity) return null;
+
+    return config.findOrCreate(identity, token);
+  };
+}

package/src/oidc.ts

@@ -0,0 +1,57 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+export interface OidcVerifyConfig {
+  issuer:    string;
+  audience?: string;
+}
+
+export interface OidcClaims {
+  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 OidcIdentity {
+  subject:  string;
+  issuer:   string;   // normalised, no trailing slash
+  email:    string;
+  name:     string;
+  picture?: string;
+}
+
+function withoutTrailingSlash(v: string): string {
+  return v.replace(/\/+$/, '');
+}
+
+/**
+ * Verify an OIDC JWT and return the normalised identity.
+ * Uses JWKS from `{issuer}/oauth/v2/keys` (Zitadel-compatible endpoint).
+ * Returns null on any verification failure — never throws to the caller.
+ */
+export async function verifyOidcToken(
+  token:  string,
+  config: OidcVerifyConfig,
+): Promise<OidcIdentity | 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 OidcClaims;
+  const subject = String(payload.sub ?? '');
+  if (!subject) return null;
+
+  const email   = String(payload.email ?? payload.preferred_username ?? `${subject}@unknown`);
+  const name    = String(payload.name  ?? payload.preferred_username ?? email);
+  const picture = payload.picture ? String(payload.picture) : undefined;
+
+  return { subject, issuer, email, name, picture };
+}

package/src/pkce.ts

@@ -0,0 +1,73 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities — RFC 7636.
+ * Runtime-agnostic: Workers, Node 20+, browser (Web Crypto API).
+ */
+
+export interface PkceChallenge {
+  verifier:  string;
+  challenge: string;
+  method:    'S256';
+}
+
+export interface OidcAuthUrlConfig {
+  /** OIDC issuer base URL, e.g. "https://nesskey.com" */
+  issuer:       string;
+  clientId:     string;
+  redirectUri:  string;
+  /** Defaults to ["openid", "email", "profile"] */
+  scopes?:      string[];
+  state?:       string;
+  challenge:    string;
+  /**
+   * OIDC prompt parameter.
+   * - "select_account" → show account chooser even if session exists (recommended for web apps)
+   * - "login"          → force re-authentication every time
+   * - "none"           → silent auth, error if no session
+   */
+  prompt?:      'select_account' | 'login' | 'none' | 'consent';
+}
+
+/** 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));
+
+  return { verifier, challenge, method: 'S256' };
+}
+
+/**
+ * Build an OIDC authorization URL with PKCE.
+ * Compatible with any OIDC provider (Zitadel, Auth0, Keycloak, etc.).
+ */
+export function buildOidcAuthUrl(config: OidcAuthUrlConfig): string {
+  const issuer = config.issuer.replace(/\/+$/, '');
+  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',
+  });
+
+  if (config.state)  params.set('state',  config.state);
+  if (config.prompt) params.set('prompt', config.prompt);
+
+  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, '');
+}