@marktiderman/genesis-connect 0.1.3 → 0.3.0

package/dist/index.d.ts

@@ -13,6 +13,11 @@ interface OAuthProvider {
     readonly authorizeUrl: string;
     /** The token endpoint (code and refresh-token grants). */
     readonly tokenUrl: string;
+    /**
+     * The OpenID Connect issuer(s) its ID tokens name in `iss`. Without it, no `identity` is read
+     * from an ID token.
+     */
+    readonly issuer?: string | readonly string[] | undefined;
     /** The revocation endpoint (RFC 7009), when the provider has one. */
     readonly revokeUrl?: string | undefined;
     /** Scopes asked for when neither the connector nor `start` names any. */
@@ -53,8 +58,14 @@ declare const GOOGLE_SCOPES: {
     readonly driveFile: "https://www.googleapis.com/auth/drive.file";
     /** Every spreadsheet the person can reach. Prefer `driveFile`. */
     readonly spreadsheets: "https://www.googleapis.com/auth/spreadsheets";
-    /** Events on the person's calendars. */
+    /** Read and change events on the person's calendars. Prefer `calendarEventsReadonly` to only read. */
     readonly calendarEvents: "https://www.googleapis.com/auth/calendar.events";
+    /** Read events on every calendar the person can see, and nothing else. */
+    readonly calendarEventsReadonly: "https://www.googleapis.com/auth/calendar.events.readonly";
+    /** The list of calendars the person has (names, colors, which are shown), not their events. */
+    readonly calendarListReadonly: "https://www.googleapis.com/auth/calendar.calendarlist.readonly";
+    /** Read everything on the person's calendars (calendars, events, settings). Prefer the two above. */
+    readonly calendarReadonly: "https://www.googleapis.com/auth/calendar.readonly";
     /** Send mail as the person. */
     readonly gmailSend: "https://www.googleapis.com/auth/gmail.send";
 };
@@ -162,14 +173,35 @@ interface ConnectedAccount<D extends StateData = StateData> {
     scope: string;
     /** The granted scopes. */
     scopes: string[];
-    /** The OpenID Connect ID token, when the provider sent one (an `openid` scope). */
+    /**
+     * The OpenID Connect ID token, when the provider sent one (an `openid` scope), as it came.
+     * Its claims are NOT checked here: read who the account is from `identity`, which is.
+     */
     idToken?: string | undefined;
+    /**
+     * Who the account is, read from the ID token: to show "connected as …" and to tell two
+     * accounts of one person apart. Only with an `openid` scope (add `email` for the address), a
+     * provider with an `issuer` and an https token endpoint; left out when the token's issuer,
+     * audience, authorized party or expiry don't check out (the connection itself still succeeds).
+     */
+    identity?: AccountIdentity | undefined;
     /** From `start`. */
     subject: string;
     intent: string;
     returnTo: string;
     data: D;
 }
+/** The account an ID token names. `subject` is the provider's stable id for it; the rest may change. */
+interface AccountIdentity {
+    /** The provider's id for the account (`sub`): stable, unique per provider. */
+    subject: string;
+    /** Only when the provider says it's verified. Never key an account on it: use `subject`. */
+    email?: string | undefined;
+    emailVerified?: boolean | undefined;
+    /** As the person set them: untrusted text and an untrusted URL. Escape or check before use. */
+    name?: string | undefined;
+    picture?: string | undefined;
+}
 /** What `store` may add to the way back, as query parameters (a grant id to finish with). */
 type StoreResult = void | undefined | Readonly<Record<string, string>>;
 /** A safe log line: never a token, a code, a secret or a provider's error text. */
@@ -225,6 +257,25 @@ interface ConnectorConfig<D extends StateData = StateData> extends HttpOptions {
     aad?: ((id: string) => string) | undefined;
     /** Fail with `failed` when the provider sends no refresh token. Default true. */
     requireRefreshToken?: boolean | undefined;
+    /**
+     * Fail with `failed` when no `identity` can be read (no ID token, or one whose issuer,
+     * audience or expiry don't check out). Default false: the connection succeeds without one,
+     * and the reason is logged.
+     */
+    requireIdentity?: boolean | undefined;
+    /**
+     * Audiences other than `clientId` an ID token's `aud` may also name (another client of the
+     * same app). Default none: a token naming any other audience gives no `identity`.
+     */
+    trustedAudiences?: readonly string[] | undefined;
+    /**
+     * Revoke the new grant (best effort, through the provider's `revokeUrl`) when the callback
+     * turns it down after the code was traded: a missing scope or, with `requireIdentity`, no
+     * identity. Default false: Google ends every token of the person's grant across the project
+     * on a revoke, so a returning person who unticks a scope would also lose the connection they
+     * already have. Set it true only when each grant is isolated (one connection per client).
+     */
+    revokeFailedGrants?: boolean | undefined;
     /**
      * Keeps the new account: the app's row, under `account.id`, for
      * `account.subject` (the user who started). Use that, never a session read
@@ -304,4 +355,4 @@ declare function clearAccessTokenCache(): void;
 /** Sets up a connector for one provider. Checks its config now, so a mistake shows at boot. */
 declare function createConnector<D extends StateData = StateData>(config: ConnectorConfig<D>): Connector<D>;
 
-export { CONNECT_RESULTS, ConnectError, type ConnectErrorCode, type ConnectLogEvent, type ConnectResult, type ConnectedAccount, type Connector, type ConnectorConfig, GOOGLE_SCOPES, type HttpOptions, type OAuthProvider, type RefreshedToken, Secrets, type StartOptions, type StartResult, type StateData, type StoreResult, type TokenCallOptions, clearAccessTokenCache, createConnector, googleProvider, isConnectError, isSafeReturnOrigin };
+export { type AccountIdentity, CONNECT_RESULTS, ConnectError, type ConnectErrorCode, type ConnectLogEvent, type ConnectResult, type ConnectedAccount, type Connector, type ConnectorConfig, GOOGLE_SCOPES, type HttpOptions, type OAuthProvider, type RefreshedToken, Secrets, type StartOptions, type StartResult, type StateData, type StoreResult, type TokenCallOptions, clearAccessTokenCache, createConnector, googleProvider, isConnectError, isSafeReturnOrigin };

package/dist/index.js

@@ -7,6 +7,7 @@ var googleProvider = {
   authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
   tokenUrl: "https://oauth2.googleapis.com/token",
   revokeUrl: "https://oauth2.googleapis.com/revoke",
+  issuer: ["https://accounts.google.com", "accounts.google.com"],
   defaultScopes: [],
   authorizeParams: {
     access_type: "offline",
@@ -33,8 +34,14 @@ var GOOGLE_SCOPES = {
   driveFile: "https://www.googleapis.com/auth/drive.file",
   /** Every spreadsheet the person can reach. Prefer `driveFile`. */
   spreadsheets: "https://www.googleapis.com/auth/spreadsheets",
-  /** Events on the person's calendars. */
+  /** Read and change events on the person's calendars. Prefer `calendarEventsReadonly` to only read. */
   calendarEvents: "https://www.googleapis.com/auth/calendar.events",
+  /** Read events on every calendar the person can see, and nothing else. */
+  calendarEventsReadonly: "https://www.googleapis.com/auth/calendar.events.readonly",
+  /** The list of calendars the person has (names, colors, which are shown), not their events. */
+  calendarListReadonly: "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+  /** Read everything on the person's calendars (calendars, events, settings). Prefer the two above. */
+  calendarReadonly: "https://www.googleapis.com/auth/calendar.readonly",
   /** Send mail as the person. */
   gmailSend: "https://www.googleapis.com/auth/gmail.send"
 };
@@ -79,6 +86,50 @@ var CONNECT_ERROR_CODES = [
 function isConnectError(error) {
   return error instanceof Error && error.name === "ConnectError" && CONNECT_ERROR_CODES.includes(error.code);
 }
+function identityFromTokenEndpoint(idToken, expect) {
+  if (expect.issuers.length === 0)
+    return { reason: "the provider names no issuer" };
+  const part = idToken.split(".")[1];
+  if (!part) return { reason: "not a JWT" };
+  let claims;
+  try {
+    const value = JSON.parse(
+      new TextDecoder().decode(fromBase64(part))
+    );
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      return { reason: "unreadable claims" };
+    claims = value;
+  } catch {
+    return { reason: "unreadable claims" };
+  }
+  if (typeof claims["iss"] !== "string" || !expect.issuers.includes(claims["iss"]))
+    return { reason: "issuer mismatch" };
+  const aud = claims["aud"];
+  const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
+  if (!audiences.includes(expect.clientId))
+    return { reason: "audience mismatch" };
+  if (audiences.some(
+    (a) => a !== expect.clientId && !(typeof a === "string" && expect.trustedAudiences.includes(a))
+  ))
+    return { reason: "untrusted audience" };
+  const azp = claims["azp"];
+  if (azp !== void 0 && azp !== expect.clientId || audiences.length > 1 && azp === void 0)
+    return { reason: "authorized party mismatch" };
+  const exp = claims["exp"];
+  if (typeof exp !== "number" || exp * 1e3 <= expect.now)
+    return { reason: "expired" };
+  const text = (key) => typeof claims[key] === "string" && claims[key] ? claims[key] : void 0;
+  const subject = text("sub");
+  if (!subject) return { reason: "no subject" };
+  const verified = claims["email_verified"] === true || claims["email_verified"] === "true";
+  return {
+    subject,
+    // The address only when the provider says it's verified: never key an account on it.
+    ...verified && text("email") ? { email: text("email"), emailVerified: true } : {},
+    ...text("name") ? { name: text("name") } : {},
+    ...text("picture") ? { picture: text("picture") } : {}
+  };
+}
 var PUBLIC_SUFFIXES = /* @__PURE__ */ new Set([
   "vercel.app",
   "netlify.app",
@@ -137,6 +188,21 @@ function checkOrigin(value, what) {
   }
   return origin;
 }
+function checkEndpoint(value, what) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConnectError("config", `The provider's ${what} is not a URL`);
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal(url.hostname))) {
+    throw new ConnectError(
+      "config",
+      `The provider's ${what} must be https (http only on localhost)`
+    );
+  }
+  return value;
+}
 function checkPath(value, what) {
   if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//") || /[\\\s\x00-\x1f\x7f]/.test(value) || value.length > 512) {
     throw new ConnectError(
@@ -173,6 +239,7 @@ function scopeList(scopes, separator) {
   return list;
 }
 var DEFAULT_TIMEOUT_MS = 1e4;
+var ABANDON_TIMEOUT_MS = 3e3;
 async function timedFetch(deps, url, init, signal) {
   const timeout = AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS);
   const combined = signal ? anySignal([timeout, signal]) : timeout;
@@ -242,6 +309,8 @@ function createConnector(config) {
       "config",
       "The provider needs an id, an authorize URL and a token URL"
     );
+  checkEndpoint(provider.tokenUrl, "token URL");
+  if (provider.revokeUrl) checkEndpoint(provider.revokeUrl, "revoke URL");
   if (!config.clientId || !config.clientSecret)
     throw new ConnectError(
       "config",
@@ -311,6 +380,21 @@ function createConnector(config) {
   );
   const aliases = provider.scopeAliases ?? {};
   const normalScope = (scope) => aliases[scope] ?? scope;
+  const asksOpenid = (scopes) => scopes.some((scope) => normalScope(scope) === "openid");
+  const issuers = (typeof provider.issuer === "string" ? [provider.issuer] : provider.issuer ?? []).filter((issuer) => typeof issuer === "string" && issuer.trim() !== "");
+  if (config.requireIdentity) {
+    if (issuers.length === 0)
+      throw new ConnectError(
+        "config",
+        `requireIdentity needs the ${provider.id} provider's issuer`
+      );
+    if (!asksOpenid(defaultScopes))
+      throw new ConnectError(
+        "config",
+        "requireIdentity needs the openid scope in the connector's scopes"
+      );
+  }
+  const trustedAudiences = [...config.trustedAudiences ?? []];
   const now = () => config.now?.() ?? Date.now();
   const log = (event) => {
     try {
@@ -561,6 +645,46 @@ ${refreshToken}`);
       tokenCache.set(await cacheKey(plain), entry);
     }
   }
+  async function revokeToken(token, hint, signal) {
+    if (!provider.revokeUrl) return false;
+    const body = new URLSearchParams({ token, token_type_hint: hint });
+    const headers = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json"
+    };
+    if (provider.revokeWithClientAuth) clientAuth(body, headers);
+    try {
+      const response = await timedFetch(
+        config,
+        provider.revokeUrl,
+        { method: "POST", headers, body: body.toString() },
+        signal
+      );
+      let gone = response.ok;
+      if (!gone && response.status === 400) {
+        gone = errorCode(await jsonBody(response)) === "invalid_token";
+      } else {
+        discard(response);
+      }
+      log({
+        step: "revoke",
+        result: gone ? "revoked" : "failed",
+        ...gone ? {} : { detail: `revoke endpoint answered ${response.status}` }
+      });
+      return gone;
+    } catch {
+      log({ step: "revoke", result: "unavailable" });
+      return false;
+    }
+  }
+  function abandonGrant(refreshToken, accessToken) {
+    if (config.revokeFailedGrants !== true) return;
+    const [token, hint] = typeof refreshToken === "string" && refreshToken ? [refreshToken, "refresh_token"] : [accessToken, "access_token"];
+    revokeToken(token, hint, AbortSignal.timeout(ABANDON_TIMEOUT_MS)).catch(
+      () => {
+      }
+    );
+  }
   return {
     provider,
     redirectUri,
@@ -593,6 +717,11 @@ ${refreshToken}`);
           "usage",
           "No scopes to ask for: give the connector or start some"
         );
+      if (config.requireIdentity && !asksOpenid(scopes))
+        throw new ConnectError(
+          "usage",
+          "requireIdentity needs the openid scope: start's scopes leave it out"
+        );
       const nonce = randomToken(16);
       const verifier = randomToken(32);
       const state = await signState({
@@ -696,8 +825,10 @@ ${refreshToken}`);
         return back(request, state, "failed", {}, "no access token");
       }
       const { scope, scopes } = granted(body, state.scopes);
-      if (!state.scopes.every((s) => scopes.includes(normalScope(s))))
+      if (!state.scopes.every((s) => scopes.includes(normalScope(s)))) {
+        abandonGrant(refreshToken, accessToken);
         return back(request, state, "scope");
+      }
       if ((config.requireRefreshToken ?? true) && (typeof refreshToken !== "string" || !refreshToken)) {
         return back(
           request,
@@ -707,6 +838,20 @@ ${refreshToken}`);
           "no refresh token (is offline access asked for?)"
         );
       }
+      const idToken = typeof body["id_token"] === "string" ? body["id_token"] : void 0;
+      const wantsIdentity = config.requireIdentity === true || asksOpenid(state.scopes);
+      const read = !wantsIdentity ? void 0 : idToken ? identityFromTokenEndpoint(idToken, {
+        issuers,
+        clientId: config.clientId,
+        trustedAudiences,
+        now: now()
+      }) : { reason: "no ID token" };
+      const identity = read && "subject" in read ? read : void 0;
+      const identityNote = read && "reason" in read ? `no identity: ${read.reason}` : void 0;
+      if (!identity && config.requireIdentity) {
+        abandonGrant(refreshToken, accessToken);
+        return back(request, state, "failed", {}, identityNote);
+      }
       let extra;
       try {
         const id = config.randomId?.() ?? crypto.randomUUID();
@@ -721,7 +866,8 @@ ${refreshToken}`);
             expiresIn: expiresIn(body),
             scope,
             scopes,
-            ...typeof body["id_token"] === "string" ? { idToken: body["id_token"] } : {},
+            ...idToken ? { idToken } : {},
+            ...identity ? { identity } : {},
             subject: state.subject,
             intent: state.intent,
             returnTo: state.returnTo,
@@ -732,7 +878,7 @@ ${refreshToken}`);
       } catch {
         return back(request, state, "failed", {}, "store threw");
       }
-      return back(request, state, "connected", extra ?? {});
+      return back(request, state, "connected", extra ?? {}, identityNote);
     },
     async refresh(sealedRefreshToken, aad, options = {}) {
       const refreshToken = await config.secrets.open(sealedRefreshToken, aad);
@@ -761,39 +907,7 @@ ${refreshToken}`);
     async revoke(sealedRefreshToken, aad, options = {}) {
       const refreshToken = await config.secrets.open(sealedRefreshToken, aad);
       tokenCache.delete(await cacheKey(refreshToken));
-      if (!provider.revokeUrl) return false;
-      const body = new URLSearchParams({
-        token: refreshToken,
-        token_type_hint: "refresh_token"
-      });
-      const headers = {
-        "content-type": "application/x-www-form-urlencoded",
-        accept: "application/json"
-      };
-      if (provider.revokeWithClientAuth) clientAuth(body, headers);
-      try {
-        const response = await timedFetch(
-          config,
-          provider.revokeUrl,
-          { method: "POST", headers, body: body.toString() },
-          options.signal
-        );
-        let gone = response.ok;
-        if (!gone && response.status === 400) {
-          gone = errorCode(await jsonBody(response)) === "invalid_token";
-        } else {
-          discard(response);
-        }
-        log({
-          step: "revoke",
-          result: gone ? "revoked" : "failed",
-          ...gone ? {} : { detail: `revoke endpoint answered ${response.status}` }
-        });
-        return gone;
-      } catch {
-        log({ step: "revoke", result: "unavailable" });
-        return false;
-      }
+      return revokeToken(refreshToken, "refresh_token", options.signal);
     }
   };
 }