@openlivesync/server 1.0.2

package/src/auth/decode-token.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { SignJWT } from "jose";
+import { decodeAccessToken } from "./decode-token.js";
+
+const TEST_SECRET = new TextEncoder().encode("test-secret");
+
+describe("decodeAccessToken", () => {
+  it("returns null for empty or invalid token", async () => {
+    expect(await decodeAccessToken("")).toBeNull();
+    expect(await decodeAccessToken("not-a-jwt")).toBeNull();
+  });
+
+  it("decodes JWT payload (decode-only) and normalizes sub, email, name, provider", async () => {
+    const token = await new SignJWT({
+      sub: "user-123",
+      email: "alice@example.com",
+      name: "Alice",
+      iss: "https://accounts.google.com",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token);
+    expect(decoded).not.toBeNull();
+    expect(decoded!.sub).toBe("user-123");
+    expect(decoded!.email).toBe("alice@example.com");
+    expect(decoded!.name).toBe("Alice");
+    expect(decoded!.provider).toBe("google");
+  });
+
+  it("uses preferred_username for email when email claim missing (Microsoft-style)", async () => {
+    const token = await new SignJWT({
+      sub: "oid-456",
+      preferred_username: "bob@tenant.com",
+      name: "Bob",
+      iss: "https://login.microsoftonline.com/tenant-id/v2.0",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token);
+    expect(decoded).not.toBeNull();
+    expect(decoded!.email).toBe("bob@tenant.com");
+    expect(decoded!.provider).toBe("microsoft");
+  });
+
+  it("treats unknown issuer as custom provider", async () => {
+    const token = await new SignJWT({
+      sub: "custom-user",
+      email: "custom@example.com",
+      iss: "https://my-auth.example.com",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token);
+    expect(decoded).not.toBeNull();
+    expect(decoded!.provider).toBe("custom");
+  });
+
+  it("with custom decodeOnly returns normalized payload without verification", async () => {
+    const token = await new SignJWT({
+      sub: "decode-only-user",
+      email: "do@example.com",
+      iss: "https://custom.issuer.example",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token, {
+      custom: { decodeOnly: true },
+    });
+    expect(decoded).not.toBeNull();
+    expect(decoded!.sub).toBe("decode-only-user");
+    expect(decoded!.email).toBe("do@example.com");
+    expect(decoded!.provider).toBe("custom");
+  });
+
+  it("with Microsoft config sets issuer/audience (verification failure returns null)", async () => {
+    const token = await new SignJWT({
+      sub: "ms-user",
+      preferred_username: "ms@tenant.com",
+      iss: "https://login.microsoftonline.com/tenant-123/v2.0",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token, {
+      microsoft: { tenantId: "tenant-123", clientId: "client-456" },
+    });
+    expect(decoded).toBeNull();
+  });
+
+  it("returns null when verification throws (e.g. invalid signature)", async () => {
+    const token = await new SignJWT({
+      sub: "user",
+      iss: "https://accounts.google.com",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const decoded = await decodeAccessToken(token, {
+      google: { clientId: "google-client" },
+    });
+    expect(decoded).toBeNull();
+  });
+});

package/src/auth/decode-token.ts

@@ -0,0 +1,138 @@
+/**
+ * Decode and optionally verify OAuth/OpenID access tokens (JWT).
+ * Supports Google, Microsoft, and custom providers (JWKS or decode-only).
+ */
+
+import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+
+export interface DecodedToken {
+  sub: string;
+  email?: string;
+  name?: string;
+  iss?: string;
+  provider?: string;
+}
+
+export interface AuthGoogleConfig {
+  /** Optional: validate audience (client ID). */
+  clientId?: string;
+}
+
+export interface AuthMicrosoftConfig {
+  tenantId: string;
+  /** Optional: validate audience (client ID). */
+  clientId?: string;
+}
+
+export interface AuthCustomConfig {
+  /** JWKS URL for signature verification. */
+  jwksUrl?: string;
+  /** Expected issuer (iss claim). */
+  issuer?: string;
+  /** If true, only decode payload (no verification). Use for dev or trusted tokens. */
+  decodeOnly?: boolean;
+}
+
+export interface AuthOptions {
+  google?: AuthGoogleConfig;
+  microsoft?: AuthMicrosoftConfig;
+  custom?: AuthCustomConfig;
+}
+
+const GOOGLE_ISSUER = "https://accounts.google.com";
+const GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs";
+
+function normalizePayload(payload: Record<string, unknown>): DecodedToken {
+  const sub = typeof payload.sub === "string" ? payload.sub : "";
+  const email =
+    typeof payload.email === "string"
+      ? payload.email
+      : typeof payload.preferred_username === "string"
+        ? payload.preferred_username
+        : undefined;
+  const name =
+    typeof payload.name === "string"
+      ? payload.name
+      : [payload.given_name, payload.family_name]
+          .filter((x) => typeof x === "string")
+          .join(" ")
+          .trim() || undefined;
+  const iss = typeof payload.iss === "string" ? payload.iss : undefined;
+  let provider: string | undefined;
+  if (iss) {
+    if (iss.includes("accounts.google.com")) provider = "google";
+    else if (iss.includes("login.microsoftonline.com")) provider = "microsoft";
+    else provider = "custom";
+  }
+  return { sub, email, name, iss, provider };
+}
+
+function getGoogleJwksUrl(): URL {
+  return new URL(GOOGLE_JWKS_URL);
+}
+
+function getMicrosoftJwksUrl(tenantId: string): URL {
+  return new URL(
+    `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`
+  );
+}
+
+/**
+ * Decode (and optionally verify) an access token JWT.
+ * Returns normalized claims (sub, email, name, provider) or null on failure.
+ * If no auth options are provided or a provider uses decodeOnly, only decoding is performed (no signature verification).
+ */
+export async function decodeAccessToken(
+  token: string,
+  options?: AuthOptions
+): Promise<DecodedToken | null> {
+  if (!token || typeof token !== "string") return null;
+
+  try {
+    const decoded = decodeJwt(token);
+    const payload = decoded as unknown as Record<string, unknown>;
+    const iss = typeof payload.iss === "string" ? payload.iss : undefined;
+
+    // Determine which provider config applies and whether to verify
+    let verifyUrl: URL | null = null;
+    let issuer: string | undefined;
+    let audience: string | undefined;
+
+    if (options?.google && iss?.includes("accounts.google.com")) {
+      verifyUrl = getGoogleJwksUrl();
+      issuer = GOOGLE_ISSUER;
+      audience = options.google.clientId;
+    } else if (
+      options?.microsoft &&
+      iss?.includes("login.microsoftonline.com")
+    ) {
+      const tenantId = options.microsoft.tenantId;
+      verifyUrl = getMicrosoftJwksUrl(tenantId);
+      issuer = `https://login.microsoftonline.com/${tenantId}/v2.0`;
+      audience = options.microsoft.clientId;
+    } else if (options?.custom) {
+      if (options.custom.decodeOnly) {
+        return normalizePayload(payload);
+      }
+      if (options.custom.jwksUrl) {
+        verifyUrl = new URL(options.custom.jwksUrl);
+        issuer = options.custom.issuer;
+      }
+    }
+
+    // No verification configured: decode only
+    if (!verifyUrl) {
+      return normalizePayload(payload);
+    }
+
+    const JWKS = createRemoteJWKSet(verifyUrl);
+    const verifyOptions: { issuer?: string; audience?: string } = {};
+    if (issuer) verifyOptions.issuer = issuer;
+    if (audience) verifyOptions.audience = audience;
+
+    const { payload: verified } = await jwtVerify(token, JWKS, verifyOptions);
+    return normalizePayload(verified as unknown as Record<string, unknown>);
+  } catch {
+    return null;
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Auth module: decode and verify OAuth/OpenID access tokens.
+ */
+
+export {
+  decodeAccessToken,
+  type DecodedToken,
+  type AuthOptions,
+  type AuthGoogleConfig,
+  type AuthMicrosoftConfig,
+  type AuthCustomConfig,
+} from "./decode-token.js";
+export {
+  createTokenAuth,
+  type CreateTokenAuthOptions,
+} from "./token-auth.js";

package/src/auth/token-auth.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi } from "vitest";
+import { SignJWT } from "jose";
+import { createTokenAuth } from "./token-auth.js";
+import type { IncomingMessage } from "node:http";
+
+const TEST_SECRET = new TextEncoder().encode("test-secret");
+
+function mockRequest(overrides: { url?: string; headers?: Record<string, string | string[] | undefined> } = {}): IncomingMessage {
+  return {
+    url: overrides.url ?? "/",
+    headers: overrides.headers ?? {},
+  } as IncomingMessage;
+}
+
+describe("createTokenAuth", () => {
+  it("returns UserInfo when token is in query access_token", async () => {
+    const token = await new SignJWT({
+      sub: "user-q",
+      email: "q@example.com",
+      name: "Query User",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const onAuth = createTokenAuth({});
+    const req = mockRequest({ url: `http://localhost/live?access_token=${token}` });
+    const result = await onAuth(req);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe("user-q");
+    expect(result!.email).toBe("q@example.com");
+    expect(result!.name).toBe("Query User");
+  });
+
+  it("returns UserInfo when token is in Authorization Bearer header", async () => {
+    const token = await new SignJWT({
+      sub: "user-h",
+      email: "h@example.com",
+      name: "Header User",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const onAuth = createTokenAuth({});
+    const req = mockRequest({ headers: { authorization: `Bearer ${token}` } });
+    const result = await onAuth(req);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe("user-h");
+    expect(result!.email).toBe("h@example.com");
+  });
+
+  it("returns null when no token in request", async () => {
+    const onAuth = createTokenAuth({});
+    const req = mockRequest({ url: "/live" });
+    const result = await onAuth(req);
+    expect(result).toBeNull();
+  });
+
+  it("returns null when token is invalid", async () => {
+    const onAuth = createTokenAuth({});
+    const req = mockRequest({ url: "http://localhost/?access_token=not-a-jwt" });
+    const result = await onAuth(req);
+    expect(result).toBeNull();
+  });
+
+  it("uses custom tokenFromRequest when provided", async () => {
+    const token = await new SignJWT({ sub: "custom", email: "c@example.com" })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(TEST_SECRET);
+
+    const tokenFromRequest = vi.fn((req: IncomingMessage) => {
+      return (req as { _token?: string })._token ?? null;
+    });
+    const req = mockRequest() as IncomingMessage & { _token?: string };
+    req._token = token;
+
+    const onAuth = createTokenAuth({}, { tokenFromRequest });
+    const result = await onAuth(req);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe("custom");
+    expect(tokenFromRequest).toHaveBeenCalledWith(req);
+  });
+
+  it("returns null when tokenFromRequest returns null", async () => {
+    const tokenFromRequest = vi.fn(() => null);
+    const onAuth = createTokenAuth({}, { tokenFromRequest });
+    const result = await onAuth(mockRequest());
+    expect(result).toBeNull();
+  });
+});

package/src/auth/token-auth.ts

@@ -0,0 +1,55 @@
+/**
+ * Helper to use access token only at WebSocket connect (query or header).
+ * Returns an onAuth function that reads the token from the request and decodes it.
+ */
+
+import type { IncomingMessage } from "node:http";
+import type { UserInfo } from "../protocol.js";
+import { decodeAccessToken } from "./decode-token.js";
+import type { AuthOptions } from "./decode-token.js";
+
+function defaultTokenFromRequest(req: IncomingMessage): string | null {
+  const url = req.url ?? "";
+  try {
+    const u = new URL(url, "http://localhost");
+    const fromQuery = u.searchParams.get("access_token");
+    if (fromQuery) return fromQuery;
+  } catch {
+    // ignore URL parse errors
+  }
+  const auth = req.headers.authorization;
+  if (typeof auth === "string" && /^Bearer\s+/i.test(auth)) {
+    return auth.replace(/^Bearer\s+/i, "").trim() || null;
+  }
+  return null;
+}
+
+export interface CreateTokenAuthOptions {
+  /** Custom way to extract token from the upgrade request. Default: query access_token or Authorization Bearer. */
+  tokenFromRequest?: (req: IncomingMessage) => string | null;
+}
+
+/**
+ * Returns an onAuth function that reads the access token from the request (query or header),
+ * decodes it with decodeAccessToken, and returns UserInfo (userId, name, email, provider).
+ * Use this so the token is used only at connect; the connection is then recognized for its lifetime.
+ */
+export function createTokenAuth(
+  authOptions: AuthOptions,
+  options?: CreateTokenAuthOptions
+): (request: IncomingMessage) => Promise<UserInfo | null> {
+  const tokenFromRequest = options?.tokenFromRequest ?? defaultTokenFromRequest;
+
+  return async (request: IncomingMessage): Promise<UserInfo | null> => {
+    const token = tokenFromRequest(request);
+    if (!token) return null;
+    const decoded = await decodeAccessToken(token, authOptions);
+    if (!decoded) return null;
+    return {
+      userId: decoded.sub,
+      name: decoded.name,
+      email: decoded.email,
+      provider: decoded.provider,
+    };
+  };
+}