okengine 0.17.2 → 0.18.4

package/src/drivers/oauth-facebook.ts

@@ -0,0 +1,80 @@
+/**
+ * `facebook` OAuth2 driver — Graph API `GET /me?fields=id,name,email`.
+ *
+ * Trust: `emailVerified` is **always false** — Facebook provides no
+ * verification signal to apps (locked decision 5). Email may be null for
+ * phone-only accounts.
+ */
+
+import {
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import { buildAuthorizeQuery } from "./oauth-shared.ts";
+import { fetchProviderJson, resolveOauth2Assertion } from "./oauth2-common.ts";
+import { postTokenRequest } from "./oauth2-token.ts";
+
+const AUTHORIZATION_SERVER_ID = "https://www.facebook.com";
+const GRAPH_VERSION = "v21.0";
+
+/** Default Facebook scopes. */
+export const FACEBOOK_DEFAULT_SCOPES = ["email", "public_profile"] as const;
+
+/**
+ * Open the Facebook driver.
+ *
+ * @param options - Optional Graph version / scope override / injectable fetch
+ */
+export function openOAuthFacebook(
+  options: {
+    readonly graphVersion?: string;
+    readonly scopes?: readonly string[];
+    readonly fetch?: typeof globalThis.fetch;
+  } = {},
+): OAuthDriver {
+  const version = options.graphVersion ?? GRAPH_VERSION;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "facebook",
+    kind: "oauth2",
+    authorizationServerId: AUTHORIZATION_SERVER_ID,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      return {
+        url: buildAuthorizeQuery(`https://www.facebook.com/${version}/dialog/oauth`, input),
+      };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      return {
+        tokens: await postTokenRequest({
+          tokenEndpoint: `https://graph.facebook.com/${version}/oauth/access_token`,
+          input,
+        }),
+      };
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      return resolveOauth2Assertion(input, async (accessToken) => {
+        const me = await fetchProviderJson(
+          `https://graph.facebook.com/${version}/me?fields=id,name,email`,
+          accessToken,
+          fetchFn,
+          "facebook",
+        );
+        const subject = typeof me["id"] === "string" ? me["id"] : undefined;
+        if (subject === undefined) throw new Error("facebook: profile missing id");
+        return {
+          providerId: "facebook",
+          subject,
+          ...(me["email"] !== undefined && me["email"] !== null ? { email: me["email"] } : {}),
+          // No trustworthy provider signal — always unverified.
+          ...(typeof me["name"] === "string" ? { name: me["name"] } : {}),
+          raw: me,
+        };
+      });
+    },
+  };
+}

package/src/drivers/oauth-figma.ts

@@ -0,0 +1,116 @@
+/**
+ * `figma` OAuth2 driver — `GET /v1/me`. No verification field exists in the
+ * API, so `emailVerified` is always false (locked decision 5). Token endpoint
+ * requires HTTP Basic client auth.
+ */
+
+import {
+  OAuthProtocolError,
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import { buildAuthorizeQuery } from "./oauth-shared.ts";
+import { fetchProviderJson, resolveOauth2Assertion } from "./oauth2-common.ts";
+
+const AUTHORIZATION_SERVER_ID = "https://www.figma.com";
+
+/** Default Figma scopes. */
+export const FIGMA_DEFAULT_SCOPES = ["file_read"] as const;
+
+function basicAuth(clientId: string, clientSecret: string): string {
+  const raw = new TextEncoder().encode(`${clientId}:${clientSecret}`);
+  let binary = "";
+  for (const b of raw) binary += String.fromCharCode(b);
+  return `Basic ${btoa(binary)}`;
+}
+
+/**
+ * Open the Figma driver.
+ *
+ * @param options - Optional scope override / injectable fetch
+ */
+export function openOAuthFigma(
+  options: { readonly scopes?: readonly string[]; readonly fetch?: typeof globalThis.fetch } = {},
+): OAuthDriver {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "figma",
+    kind: "oauth2",
+    authorizationServerId: AUTHORIZATION_SERVER_ID,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      return { url: buildAuthorizeQuery("https://www.figma.com/oauth", input) };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      if (!input.clientSecret) {
+        throw new OAuthProtocolError("missing_secret", "figma requires a client secret");
+      }
+      const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        client_id: input.clientId,
+        code_verifier: input.codeVerifier,
+      });
+      const res = await fetchFn("https://api.figma.com/v1/oauth/token", {
+        method: "POST",
+        headers: {
+          authorization: basicAuth(input.clientId, input.clientSecret),
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+        },
+        body: params.toString(),
+      });
+      const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      if (!res.ok || typeof body["access_token"] !== "string") {
+        throw new OAuthProtocolError(
+          "exchange_failed",
+          `figma token endpoint returned HTTP ${res.status}: ${String(body["err"] ?? body["error"] ?? "unknown")}`,
+        );
+      }
+      const expiresIn = body["expires_in"];
+      return {
+        tokens: {
+          accessToken: body["access_token"],
+          ...(typeof body["refresh_token"] === "string"
+            ? { refreshToken: body["refresh_token"] as string }
+            : {}),
+          ...(typeof expiresIn === "number"
+            ? { expiresAt: Math.floor(Date.now() / 1000 + expiresIn * 1000) }
+            : {}),
+          ...(typeof body["scope"] === "string" ? { scopes: [body["scope"] as string] } : {}),
+          raw: body,
+        },
+      };
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      return resolveOauth2Assertion(input, async (accessToken) => {
+        const me = await fetchProviderJson(
+          "https://api.figma.com/v1/me",
+          accessToken,
+          fetchFn,
+          "figma",
+        );
+        const subject =
+          typeof me["id"] === "string"
+            ? me["id"]
+            : typeof me["handle"] === "string"
+              ? me["handle"]
+              : undefined;
+        if (subject === undefined) throw new Error("figma: profile missing id");
+        return {
+          providerId: "figma",
+          subject,
+          ...(me["email"] !== undefined && me["email"] !== null ? { email: me["email"] } : {}),
+          // API exposes no verification field — always unverified.
+          ...(typeof me["handle"] === "string" ? { name: me["handle"] } : {}),
+          raw: me,
+        };
+      });
+    },
+  };
+}

package/src/drivers/oauth-github.ts

@@ -0,0 +1,92 @@
+/**
+ * `github` OAuth2 driver — `GET /user` plus **`GET /user/emails`** (the
+ * `/user` `email` field is often null; the primary verified email requires
+ * the `user:email` scope). Trust: `primary.verified === true`.
+ */
+
+import {
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import { buildAuthorizeQuery } from "./oauth-shared.ts";
+import { fetchProviderJson, resolveOauth2Assertion } from "./oauth2-common.ts";
+import { postTokenRequest } from "./oauth2-token.ts";
+
+const AUTHORIZATION_SERVER_ID = "https://github.com";
+
+/** Default GitHub scopes. */
+export const GITHUB_DEFAULT_SCOPES = ["read:user", "user:email"] as const;
+
+/**
+ * Open the GitHub driver.
+ *
+ * @param options - Optional scope override / injectable fetch
+ */
+export function openOAuthGithub(
+  options: { readonly scopes?: readonly string[]; readonly fetch?: typeof globalThis.fetch } = {},
+): OAuthDriver {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "github",
+    kind: "oauth2",
+    authorizationServerId: AUTHORIZATION_SERVER_ID,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      // GitHub PKCE is accepted and forwarded even though not OIDC.
+      return { url: buildAuthorizeQuery("https://github.com/login/oauth/authorize", input) };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      return {
+        tokens: await postTokenRequest({
+          tokenEndpoint: "https://github.com/login/oauth/access_token",
+          input,
+        }),
+      };
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      return resolveOauth2Assertion(input, async (accessToken) => {
+        const user = await fetchProviderJson(
+          "https://api.github.com/user",
+          accessToken,
+          fetchFn,
+          "github",
+        );
+        const subject = typeof user["id"] === "number" ? String(user["id"]) : undefined;
+        if (subject === undefined) throw new Error("github: profile missing numeric id");
+        const login = typeof user["login"] === "string" ? user.login : undefined;
+        const emails = await fetchProviderJson(
+          "https://api.github.com/user/emails",
+          accessToken,
+          fetchFn,
+          "github",
+        ).catch(() => undefined);
+        const list: readonly unknown[] = Array.isArray(emails) ? emails : [];
+        const parsed = list.filter(isGitHubEmail);
+        const primary = parsed.find((e) => e.primary === true) ?? parsed[0];
+        return {
+          providerId: "github",
+          subject,
+          ...(primary?.email !== undefined ? { email: primary.email } : {}),
+          // Trust only an explicit verified flag on the selected entry.
+          ...(primary !== undefined ? { verified: primary.verified } : {}),
+          ...(login !== undefined ? { name: login } : {}),
+          raw: user,
+        };
+      });
+    },
+  };
+}
+
+interface GitHubEmail {
+  readonly email?: string;
+  readonly primary?: boolean;
+  readonly verified?: boolean;
+}
+
+function isGitHubEmail(value: unknown): value is GitHubEmail {
+  return typeof value === "object" && value !== null;
+}

package/src/drivers/oauth-google.ts

@@ -0,0 +1,142 @@
+/**
+ * `google` OIDC driver — Authorization Code + PKCE against
+ * `https://accounts.google.com`. Mix-up anchor: ID token
+ * `iss=https://accounts.google.com` (RFC 9207 also honored via the same
+ * equality check when Google includes it).
+ */
+
+import {
+  OAuthProtocolError,
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import {
+  buildAuthorizeQuery,
+  formPost,
+  normalizeEmail,
+  parseEmailVerified,
+} from "./oauth-shared.ts";
+import { discoverOpenId, verifyIdToken } from "./oauth-oidc.ts";
+
+const AUTHORIZATION_SERVER_ID = "https://accounts.google.com";
+
+/**
+ * Open the Google driver.
+ *
+ * @param options - Optional scope override / injectable fetch
+ */
+export function openOAuthGoogle(
+  options: { readonly scopes?: readonly string[]; readonly fetch?: typeof globalThis.fetch } = {},
+): OAuthDriver {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "google",
+    kind: "oidc",
+    authorizationServerId: AUTHORIZATION_SERVER_ID,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      return {
+        url: buildAuthorizeQuery(
+          `${AUTHORIZATION_SERVER_ID}/o/oauth2/v2/auth`,
+          input,
+          // Always (re)select accounts — never an untargeted session.
+          { prompt: "select_account" },
+        ),
+      };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      if (!input.clientSecret) {
+        throw new OAuthProtocolError("missing_secret", "google requires a client secret");
+      }
+      const endpoints = await discoverOpenId(AUTHORIZATION_SERVER_ID, fetchFn);
+      return exchangeForm(endpoints.tokenEndpoint, input);
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      if (!input.tokens.idToken) {
+        throw new OAuthProtocolError("missing_id_token", "google token response missing id_token");
+      }
+      const claims = await verifyIdToken({
+        idToken: input.tokens.idToken,
+        jwksUri: `${AUTHORIZATION_SERVER_ID}/oauth2/v3/certs`,
+        expectedIssuer: input.expectedIssuer,
+        expectedAudience: input.expectedAudience,
+        ...(input.expectedNonce !== undefined ? { expectedNonce: input.expectedNonce } : {}),
+        fetchFn,
+        ...(input.now !== undefined ? { now: input.now } : {}),
+      });
+      const email = normalizeEmail(claims.payload["email"]);
+      return {
+        subject: claims.subject,
+        issuer: claims.issuer,
+        ...(email !== undefined ? { email } : {}),
+        emailVerified: parseEmailVerified(claims.payload["email_verified"]),
+        ...(typeof claims.payload["name"] === "string"
+          ? { name: claims.payload["name"] as string }
+          : {}),
+        raw: claims.payload,
+      };
+    },
+  };
+}
+
+/** Shared form POST for OIDC token exchanges (Google). */
+export async function exchangeForm(
+  tokenEndpoint: string,
+  input: OAuthExchangeInput,
+): Promise<OAuthExchangeResult> {
+  const clientSecret =
+    input.clientSecretJwt !== undefined ? await input.clientSecretJwt() : input.clientSecret;
+  if (!clientSecret) {
+    throw new OAuthProtocolError("missing_secret", "token exchange requires a client secret");
+  }
+  const fetchFn = input.fetch ?? globalThis.fetch;
+  const res = await fetchFn(
+    tokenEndpoint,
+    formPost({
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      client_id: input.clientId,
+      client_secret: clientSecret,
+      code_verifier: input.codeVerifier,
+    }),
+  );
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!res.ok || typeof body["access_token"] !== "string") {
+    throw new OAuthProtocolError(
+      "exchange_failed",
+      `Token endpoint returned HTTP ${res.status}: ${String(body["error"] ?? "unknown")}`,
+    );
+  }
+  return { tokens: tokensFromResponse(body) };
+}
+
+/** Normalize a provider token response into an {@link OAuthTokenSet}-shape. */
+export function tokensFromResponse(body: Record<string, unknown>) {
+  const expiresIn = body["expires_in"];
+  const nowSec = Date.now() / 1000;
+  return {
+    accessToken: requireAccessToken(body),
+    ...(typeof body["refresh_token"] === "string"
+      ? { refreshToken: body["refresh_token"] as string }
+      : {}),
+    ...(typeof expiresIn === "number" ? { expiresAt: Math.floor(nowSec + expiresIn * 1000) } : {}),
+    ...(typeof body["scope"] === "string"
+      ? { scopes: (body["scope"] as string).split(/\s+/).filter((s) => s.length > 0) }
+      : {}),
+    ...(typeof body["id_token"] === "string" ? { idToken: body["id_token"] as string } : {}),
+    raw: body,
+  };
+}
+
+function requireAccessToken(body: Record<string, unknown>): string {
+  const token = body["access_token"];
+  if (typeof token !== "string" || token.length === 0) {
+    throw new OAuthProtocolError("exchange_failed", "Token response missing access_token");
+  }
+  return token;
+}

package/src/drivers/oauth-microsoft.ts

@@ -0,0 +1,174 @@
+/**
+ * `microsoft` OIDC driver — Entra ID v2.0 endpoints, `tenant` selector
+ * (default `common`: personal MSA + work/school).
+ *
+ * Issuer nuance: discovery under `common` / `organizations` / `consumers`
+ * advertises `https://login.microsoftonline.com/{tenantid}/v2.0`, so the flow
+ * record stores that template as `expectedIssuer` and the callback validates
+ * the concrete token `iss` against the per-tenant regex with a matching
+ * GUID-shaped `tid` claim.
+ */
+
+import {
+  OAuthProtocolError,
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import { buildAuthorizeQuery, normalizeEmail, parseEmailVerified } from "./oauth-shared.ts";
+import { discoverOpenId, verifyIdToken } from "./oauth-oidc.ts";
+
+const LOGIN_ORIGIN = "https://login.microsoftonline.com";
+const TENANT_TEMPLATE_ISSUER = `${LOGIN_ORIGIN}/{tenantid}/v2.0`;
+const CONCRETE_ISSUER_RE = /^https:\/\/login\.microsoftonline\.com\/([0-9a-fA-F-]{36})\/v2\.0$/;
+
+/** Microsoft tenant selector or concrete tenant id. */
+export type MicrosoftTenant = "common" | "organizations" | "consumers" | string;
+
+/**
+ * Open the Microsoft driver.
+ *
+ * @param options - Tenant selector + injectable fetch
+ */
+export function openOAuthMicrosoft(
+  options: {
+    readonly tenant?: MicrosoftTenant;
+    readonly scopes?: readonly string[];
+    readonly fetch?: typeof globalThis.fetch;
+  } = {},
+): OAuthDriver {
+  const tenant = options.tenant ?? "common";
+  const discoveryIssuer = `${LOGIN_ORIGIN}/${tenant}/v2.0`;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "microsoft",
+    kind: "oidc",
+    // Flow records store the {tenantid} template — never the discovery URL.
+    authorizationServerId: TENANT_TEMPLATE_ISSUER,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      return {
+        url: buildAuthorizeQuery(`${discoveryIssuer}/authorize`, input, {
+          response_mode: "query",
+        }),
+      };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      if (!input.clientSecret) {
+        throw new OAuthProtocolError("missing_secret", "microsoft requires a client secret");
+      }
+      const endpoints = await discoverOpenId(discoveryIssuer, fetchFn);
+      const res = await fetchFn(endpoints.tokenEndpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code: input.code,
+          redirect_uri: input.redirectUri,
+          client_id: input.clientId,
+          client_secret: input.clientSecret,
+          code_verifier: input.codeVerifier,
+        }).toString(),
+      });
+      const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      if (!res.ok || typeof body["access_token"] !== "string") {
+        throw new OAuthProtocolError(
+          "exchange_failed",
+          `Token endpoint returned HTTP ${res.status}: ${String(body["error"] ?? "unknown")}`,
+        );
+      }
+      const expiresIn = body["expires_in"];
+      return {
+        tokens: {
+          accessToken: body["access_token"],
+          ...(typeof body["refresh_token"] === "string"
+            ? { refreshToken: body["refresh_token"] as string }
+            : {}),
+          ...(typeof expiresIn === "number"
+            ? { expiresAt: Math.floor(Date.now() / 1000 + expiresIn * 1000) }
+            : {}),
+          ...(typeof body["scope"] === "string" ? { scopes: [body["scope"] as string] } : {}),
+          ...(typeof body["id_token"] === "string" ? { idToken: body["id_token"] as string } : {}),
+          raw: body,
+        },
+      };
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      if (!input.tokens.idToken) {
+        throw new OAuthProtocolError(
+          "missing_id_token",
+          "microsoft token response missing id_token",
+        );
+      }
+      const claims = await verifyMicrosoftIdToken({
+        idToken: input.tokens.idToken,
+        expectedAudience: input.expectedAudience,
+        ...(input.expectedNonce !== undefined ? { expectedNonce: input.expectedNonce } : {}),
+        fetchFn,
+        ...(input.now !== undefined ? { now: input.now } : {}),
+      });
+      const email =
+        normalizeEmail(claims.payload["email"]) ??
+        normalizeEmail(claims.payload["preferred_username"]);
+      return {
+        subject: claims.subject,
+        issuer: claims.issuer,
+        ...(email !== undefined ? { email } : {}),
+        emailVerified: parseEmailVerified(claims.payload["email_verified"]),
+        ...(typeof claims.payload["name"] === "string"
+          ? { name: claims.payload["name"] as string }
+          : {}),
+        raw: claims.payload,
+      };
+    },
+  };
+}
+
+/**
+ * Verify a Microsoft ID token: standard OIDC checks against the concrete
+ * per-tenant issuer (`…/{tid}/v2.0`) plus `tid` shape validation — the
+ * `{tenantid}` discovery template is never accepted as a literal issuer.
+ *
+ * @param options - Token + expectations + injectable fetch/clock
+ */
+async function verifyMicrosoftIdToken(options: {
+  readonly idToken: string;
+  readonly expectedAudience: string;
+  readonly expectedNonce?: string;
+  readonly fetchFn: typeof globalThis.fetch;
+  readonly now?: () => number;
+}): Promise<{ payload: Record<string, unknown>; subject: string; issuer: string }> {
+  const parsed = await import("./oauth-shared.ts").then((m) => m.parseJwt(options.idToken));
+  const iss = parsed.payload["iss"];
+  if (typeof iss !== "string") {
+    throw new OAuthProtocolError("issuer_mismatch", "ID token missing iss");
+  }
+  const match = CONCRETE_ISSUER_RE.exec(iss);
+  if (!match) {
+    throw new OAuthProtocolError(
+      "issuer_mismatch",
+      `ID token iss ${iss} is not a concrete login.microsoftonline.com tenant issuer`,
+    );
+  }
+  const tid = parsed.payload["tid"];
+  if (typeof tid !== "string" || !/^[0-9a-fA-F-]{36}$/.test(tid)) {
+    throw new OAuthProtocolError("tenant_mismatch", "ID token tid is not a GUID");
+  }
+
+  const claims = await verifyIdToken({
+    idToken: options.idToken,
+    jwksUri: `${iss}/discovery/v2.0/keys`,
+    expectedIssuer: iss,
+    expectedAudience: options.expectedAudience,
+    ...(options.expectedNonce !== undefined ? { expectedNonce: options.expectedNonce } : {}),
+    fetchFn: options.fetchFn,
+    ...(options.now !== undefined ? { now: options.now } : {}),
+  });
+  return claims;
+}