@uln/auth 0.4.1 → 0.6.0

package/dist/remote.d.ts

@@ -0,0 +1,52 @@
+import type { PublicKeyEntry, TokenPayload } from "./types.ts";
+/** Anything with a Fetch-compatible `fetch` — the global `fetch` wrapped, or a Cloudflare service binding. */
+export interface FetchLike {
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+}
+/** Calls the auth service over the public internet. */
+export declare function publicFetcher(authUrl: string): FetchLike;
+/** Calls the auth service through a Cloudflare service binding. The hostname is ignored by bindings. */
+export declare function bindingFetcher(binding: {
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+}): FetchLike;
+/**
+ * Whether a validated token grants access to `origin`. The token's `aud` must be this origin — a token issued to
+ * another site (or to the auth service itself) is never accepted, even for admins. Then admins can access every
+ * site; everyone else needs the origin in their `scopes` (loopback origins are exempt so local development works).
+ *
+ * A valid signature alone only proves the user has *an* account — every consuming site must also run this check.
+ */
+export declare function hasSiteAccess(payload: TokenPayload, origin: string): boolean;
+/**
+ * `hasSiteAccess` for a site that answers on more than one origin — e.g. a Worker whose request URL origin (where the
+ * login callback landed, and so the token's audience) differs from the origin registered for scopes.
+ */
+export declare function hasSiteAccessFor(payload: TokenPayload, site: {
+    audiences: string[];
+    scopeOrigin: string;
+}): boolean;
+/**
+ * POST /api/exchange-code — trade a one-time `?code=` for a signed token bound to `redirectOrigin`. `codeVerifier` is
+ * the PKCE verifier whose challenge went out with the login (required for codes issued with one).
+ */
+export declare function exchangeAuthCode(auth: FetchLike, code: string, redirectOrigin: string, codeVerifier?: string): Promise<string | null>;
+export type RemoteCheck = {
+    status: "valid";
+    payload: TokenPayload;
+} | {
+    status: "invalid";
+}
+/** Network error or 5xx — the auth service didn't give an answer. */
+ | {
+    status: "unavailable";
+};
+/**
+ * POST /api/verify-token — validate a token with the auth service itself. Unlike local JWKS validation this also
+ * rejects tokens for deleted users or revoked sessions, and returns the user's *current* admin/scopes/flags. With an
+ * `audience`, the auth service also rejects tokens issued to any other origin.
+ */
+export declare function checkTokenRemote(auth: FetchLike, token: string, audience?: string): Promise<RemoteCheck>;
+/** `checkTokenRemote`, collapsed to the payload or null (an unreachable auth service counts as invalid). */
+export declare function verifyTokenRemote(auth: FetchLike, token: string, audience?: string): Promise<TokenPayload | null>;
+/** Fetch and import the auth service's JWKS (`/.well-known/jwk.json`). Keys without a string `kid` are skipped. */
+export declare function fetchJwks(auth: FetchLike): Promise<PublicKeyEntry[]>;

package/dist/remote.js

@@ -0,0 +1,264 @@
+// @bun
+// src/token.ts
+var encoder = new TextEncoder;
+function base64urlEncode(data) {
+  let binary = "";
+  for (const byte of data) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(str) {
+  if (!/^[A-Za-z0-9_-]*$/.test(str))
+    throw new Error("Invalid base64url");
+  const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+var ECDSA_PARAMS = { name: "ECDSA", namedCurve: "P-256" };
+var SIGN_PARAMS = { name: "ECDSA", hash: "SHA-256" };
+async function generateKeyPair() {
+  const kid = crypto.randomUUID().slice(0, 8);
+  const keyPair = await crypto.subtle.generateKey(ECDSA_PARAMS, true, ["sign", "verify"]);
+  if (!("privateKey" in keyPair))
+    throw new Error("Expected CryptoKeyPair from ECDSA generateKey");
+  const privateExport = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+  const publicExport = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
+  if (privateExport instanceof ArrayBuffer || publicExport instanceof ArrayBuffer)
+    throw new Error("Expected JWK from exportKey");
+  return { kid, privateKeyJwk: privateExport, publicKeyJwk: publicExport };
+}
+async function importPrivateKey(jwk) {
+  return crypto.subtle.importKey("jwk", jwk, ECDSA_PARAMS, false, ["sign"]);
+}
+async function importPublicKey(jwk) {
+  return crypto.subtle.importKey("jwk", jwk, ECDSA_PARAMS, false, ["verify"]);
+}
+async function createToken(config, user, options = {}) {
+  const now = options.issuedAt ?? Math.floor(Date.now() / 1000);
+  const payload = {
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    admin: user.isAdmin,
+    scopes: user.scopes,
+    flags: user.flags,
+    kid: config.kid,
+    iat: now,
+    exp: now + config.maxAgeSeconds,
+    ...user.audience === undefined ? {} : { aud: user.audience }
+  };
+  const payloadB64 = base64urlEncode(encoder.encode(JSON.stringify(payload)));
+  const payloadBytes = encoder.encode(payloadB64);
+  const signature = await crypto.subtle.sign(SIGN_PARAMS, config.privateKey, payloadBytes);
+  const sigB64 = base64urlEncode(new Uint8Array(signature));
+  return `${payloadB64}.${sigB64}`;
+}
+var CLOCK_SKEW_SECONDS = 60;
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function isFlags(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  return Object.values(value).every(isStringArray);
+}
+function isTokenPayload(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  if (!("sub" in value) || !("email" in value) || !("name" in value) || !("admin" in value) || !("scopes" in value) || !("flags" in value) || !("kid" in value) || !("iat" in value) || !("exp" in value)) {
+    return false;
+  }
+  return typeof value.sub === "string" && typeof value.email === "string" && typeof value.name === "string" && typeof value.admin === "boolean" && isStringArray(value.scopes) && isFlags(value.flags) && typeof value.kid === "string" && Number.isSafeInteger(value.iat) && Number.isSafeInteger(value.exp) && (!("aud" in value) || value.aud === undefined || typeof value.aud === "string");
+}
+async function validateToken(config, token) {
+  const parts = token.split(".");
+  if (parts.length !== 2)
+    return null;
+  const [payloadB64 = "", sigB64 = ""] = parts;
+  if (!payloadB64 || !sigB64)
+    return null;
+  let decoded;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+  } catch {
+    return null;
+  }
+  if (!isTokenPayload(decoded))
+    return null;
+  const payload = decoded;
+  const now = Math.floor(Date.now() / 1000);
+  if (now > payload.exp)
+    return null;
+  if (payload.iat > now + CLOCK_SKEW_SECONDS)
+    return null;
+  if (now - payload.iat > config.maxAgeSeconds)
+    return null;
+  const entry = config.publicKeys.find((k) => k.kid === payload.kid);
+  if (!entry)
+    return null;
+  try {
+    const signatureBytes = base64urlDecode(sigB64);
+    const payloadBytes = encoder.encode(payloadB64);
+    const valid = await crypto.subtle.verify(SIGN_PARAMS, entry.key, signatureBytes, payloadBytes);
+    if (!valid)
+      return null;
+  } catch {
+    return null;
+  }
+  return payload;
+}
+function peekTokenPayload(token) {
+  const payloadB64 = token.split(".")[0];
+  if (!payloadB64)
+    return null;
+  try {
+    const decoded = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+    return isTokenPayload(decoded) ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+function peekTokenKid(token) {
+  const payloadB64 = token.split(".")[0];
+  if (!payloadB64)
+    return null;
+  try {
+    const decoded = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+    if (typeof decoded !== "object" || decoded === null || !("kid" in decoded))
+      return null;
+    return typeof decoded.kid === "string" ? decoded.kid : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/remote.ts
+function publicFetcher(authUrl) {
+  return { fetch: (path, init) => fetch(new URL(path, authUrl), init) };
+}
+function bindingFetcher(binding) {
+  return { fetch: (path, init) => binding.fetch(new URL(path, "https://auth").toString(), init) };
+}
+function isLoopbackHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function toOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+function hasSiteAccess(payload, origin) {
+  return hasSiteAccessFor(payload, { audiences: [origin], scopeOrigin: origin });
+}
+function hasSiteAccessFor(payload, site) {
+  const scopeOrigin = toOrigin(site.scopeOrigin);
+  if (!scopeOrigin || payload.aud === undefined)
+    return false;
+  if (!site.audiences.some((audience) => toOrigin(audience) === payload.aud))
+    return false;
+  if (payload.admin)
+    return true;
+  if (isLoopbackHostname(new URL(scopeOrigin).hostname))
+    return true;
+  return payload.scopes.includes(scopeOrigin);
+}
+async function readJsonObject(res) {
+  try {
+    const body = await res.json();
+    return typeof body === "object" && body !== null ? body : null;
+  } catch {
+    return null;
+  }
+}
+async function exchangeAuthCode(auth, code, redirectOrigin, codeVerifier) {
+  const res = await auth.fetch("/api/exchange-code", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(codeVerifier === undefined ? { code, redirectOrigin } : { code, redirectOrigin, codeVerifier })
+  });
+  if (!res.ok)
+    return null;
+  const body = await readJsonObject(res);
+  if (!body || !("token" in body) || typeof body.token !== "string")
+    return null;
+  return body.token;
+}
+async function checkTokenRemote(auth, token, audience) {
+  let res;
+  try {
+    res = await auth.fetch("/api/verify-token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(audience === undefined ? { token } : { token, audience })
+    });
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (res.status >= 500)
+    return { status: "unavailable" };
+  if (!res.ok)
+    return { status: "invalid" };
+  const body = await readJsonObject(res);
+  if (!body || !("user" in body) || typeof body.user !== "object" || body.user === null)
+    return { status: "invalid" };
+  const user = body.user;
+  if (!("id" in user))
+    return { status: "invalid" };
+  const candidate = { ...user, sub: user.id, iat: "iat" in user ? user.iat : 0, exp: "exp" in user ? user.exp : 0 };
+  if (!isTokenPayload(candidate))
+    return { status: "invalid" };
+  return {
+    status: "valid",
+    payload: {
+      sub: candidate.sub,
+      email: candidate.email,
+      name: candidate.name,
+      admin: candidate.admin,
+      scopes: candidate.scopes,
+      flags: candidate.flags,
+      kid: candidate.kid,
+      iat: candidate.iat,
+      exp: candidate.exp,
+      ...candidate.aud === undefined ? {} : { aud: candidate.aud }
+    }
+  };
+}
+async function verifyTokenRemote(auth, token, audience) {
+  const result = await checkTokenRemote(auth, token, audience);
+  return result.status === "valid" ? result.payload : null;
+}
+async function fetchJwks(auth) {
+  const res = await auth.fetch("/.well-known/jwk.json");
+  if (!res.ok)
+    throw new Error(`Failed to fetch JWKS: ${res.status}`);
+  const body = await readJsonObject(res);
+  if (!body || !("keys" in body) || !Array.isArray(body.keys))
+    throw new Error("Malformed JWKS response");
+  const entries = [];
+  for (const jwk of body.keys) {
+    if (typeof jwk !== "object" || jwk === null || !("kid" in jwk) || typeof jwk.kid !== "string")
+      continue;
+    if (!("kty" in jwk) || typeof jwk.kty !== "string")
+      continue;
+    const { kid, ...keyData } = jwk;
+    entries.push({ kid, key: await importPublicKey({ ...keyData, kty: jwk.kty }) });
+  }
+  return entries;
+}
+export {
+  bindingFetcher,
+  checkTokenRemote,
+  exchangeAuthCode,
+  fetchJwks,
+  hasSiteAccess,
+  hasSiteAccessFor,
+  publicFetcher,
+  verifyTokenRemote
+};

package/dist/service.d.ts

@@ -1,24 +1,24 @@
 import type { CookieConfig, TokenPayload } from "./types.ts";
-export { makeSessionCookie, makeClearCookie } from "./cookie.ts";
-export type { TokenPayload, CookieConfig } from "./types.ts";
+export { makeClearCookie, makeSessionCookie } from "./cookie.ts";
+export { redirectToLogin } from "./flow.ts";
+export { hasSiteAccess } from "./remote.ts";
+export type { CookieConfig, TokenPayload } from "./types.ts";
 /**
  * Validate a raw token string via the auth service binding.
- * Returns the token payload or null if invalid.
+ * Returns the token payload (with the user's current admin/scopes/flags) or null if invalid or revoked. Pass the
+ * site's origin as `audience` so tokens issued to other origins are rejected too.
+ * This does not check site access — use `getAuthUser` or `hasSiteAccess` for that.
  */
-export declare function verifyToken(authService: Fetcher, token: string): Promise<TokenPayload | null>;
+export declare function verifyToken(authService: Fetcher, token: string, audience?: string): Promise<TokenPayload | null>;
 /**
  * Get the authenticated user from the session cookie via the auth service binding.
- * Returns the token payload or null if not authenticated.
+ * Returns null if not authenticated, or if the token wasn't issued to — or the user doesn't have access to —
+ * `siteOrigin` (defaults to the request's origin).
  */
-export declare function getAuthUser(request: Request, authService: Fetcher, cookieConfig: CookieConfig): Promise<TokenPayload | null>;
-/**
- * Redirect to the centralized login page at auth.uln.industries.
- * Requests one-time auth-code callbacks so signed tokens are not sent through URLs.
- */
-export declare function redirectToLogin(currentUrl: string): Response;
+export declare function getAuthUser(request: Request, authService: Fetcher, cookieConfig: CookieConfig, siteOrigin?: string): Promise<TokenPayload | null>;
 /**
  * Handle an auth callback on a consuming Worker using the auth service binding.
- * Preferred `?code=` callbacks are exchanged for signed tokens before setting the local cookie.
- * Returns null if the request has no auth callback parameters.
+ * `?code=` callbacks started by this browser are exchanged for signed tokens before setting the local cookie.
+ * Returns 403 if the user doesn't have access to this site, or null if the request has no callback parameters.
  */
 export declare function handleCallback(request: Request, authService: Fetcher, cookieConfig: CookieConfig): Promise<Response | null>;