@marktiderman/genesis-connect 0.1.3 → 0.3.0

package/README.md

@@ -73,6 +73,67 @@ On the way back the page reads `?connect=`: `connected`, `expired` (start again)
 the app needs) or `failed`. Register `https://<your origin>/api/connect/google/callback` as an
 authorized redirect URI in the Google Cloud console.
 
+## Connect Google Calendar (read only)
+
+Each person connects their own Google account and the app reads their calendars. Ask for the
+two narrow read scopes plus `openid` and `email`, so the account says who it is:
+
+```ts
+export const googleCalendar = createConnector({
+  provider: googleProvider,
+  clientId: process.env.GOOGLE_OAUTH_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_OAUTH_CLIENT_SECRET!,
+  stateSecret: process.env.CONNECT_STATE_SECRET!,
+  secrets: createSecrets(process.env.CONNECT_KEYRING!, {
+    purpose: "google-refresh-token",
+  }),
+  callbackPath: "/api/connect/google/callback",
+  scopes: [
+    GOOGLE_SCOPES.openid,
+    GOOGLE_SCOPES.email,
+    GOOGLE_SCOPES.calendarListReadonly,
+    GOOGLE_SCOPES.calendarEventsReadonly,
+  ],
+  // Without a checked identity the connection fails, so every grant names its Google account.
+  requireIdentity: true,
+  store: async (account) => {
+    // account.identity: { subject, email?, emailVerified?, name?, picture? } from the ID token.
+    // Key the account on identity.subject, never on the email.
+    const google = account.identity!;
+    await db.insert("google_grants", {
+      id: account.id,
+      user_id: account.subject,
+      google_account: google.subject,
+      email: google.email ?? null,
+      refresh_token: account.sealedRefreshToken,
+      scope: account.scope,
+    });
+  },
+});
+```
+
+`identity` is read from the ID token the token endpoint sent over TLS (`createConnector`
+refuses a provider whose `tokenUrl` or `revokeUrl` isn't https, except on localhost). Its
+signature isn't checked (OpenID Connect allows that only for a token taken straight from the
+token endpoint), but its claims are: the issuer is the provider's `issuer`; the audience names
+this client and no other audience (unless it is in `trustedAudiences`); `azp`, when present, is
+this client, and is present when there are several audiences; and it hasn't expired. It is read
+only when the attempt asked for `openid` (or `requireIdentity` is set). When a check fails (or
+no ID token comes), `identity` is left out, the reason is logged (`callback` event), and the
+connection still succeeds unless `requireIdentity` is set, which fails it instead and revokes
+the new grant. `requireIdentity` needs the provider's `issuer` and `openid` in the connector's
+`scopes`, or `createConnector` throws `config`. `email` is there only when the provider says
+it's verified; never key an account on it, use `subject`. `name` and `picture` are whatever
+the person set: treat them as untrusted (escape the name, check the URL before loading it).
+`account.idToken` is the raw token with unchecked claims; read `identity` instead. The kit
+fetches no calendar data: with `accessToken(...)`, the app calls the Calendar API
+(`calendarList`, then `events` with `singleEvents=true` and a sync token) and keeps the rows.
+Calendar scopes are sensitive. While the app's OAuth consent screen is in the **Testing**
+publishing status, only the test users listed on it (up to 100) can connect, and their grants
+and refresh tokens expire seven days after consent. Once it is **In production**, anyone can
+connect, but until Google verifies the app it shows the unverified-app warning and caps how
+many people can sign in.
+
 ## Secrets and key rotation
 
 ```ts
@@ -111,13 +172,13 @@ if (secrets.needsRotation(row.sealed))
 
 `createConnector(config)` checks its config at boot and returns:
 
-| Call                                                                      | What it does                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start(request, { subject, intent?, returnTo, scopes?, data?, params? })` | The provider's sign-in URL and a `Set-Cookie`. `.redirect()` answers a 303; `.json()` answers `{ url }` for a page that navigates itself.                                                                                                                                                                     |
-| `callback(request)`                                                       | Checks the signed state (signature, age), that the cookie's nonce matches it, handles `error`, exchanges the code with the PKCE verifier, checks every scope asked for was granted, seals the refresh token and calls `store`. Always a 303 back to `returnTo` with `?connect=<result>`, clearing the cookie. |
-| `accessToken(sealed, aad)`                                                | A fresh access token, cached in memory until a minute before it expires.                                                                                                                                                                                                                                      |
-| `refresh(sealed, aad, { onRotate })`                                      | Uncached; when the provider rotates the refresh token, the new one comes back sealed.                                                                                                                                                                                                                         |
-| `revoke(sealed, aad)`                                                     | Revokes at the provider and forgets the cached token. True when it is gone. Google ends every token of the person's grant to your client, so only revoke the last connection that uses it.                                                                                                                    |
+| Call                                                                      | What it does                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start(request, { subject, intent?, returnTo, scopes?, data?, params? })` | The provider's sign-in URL and a `Set-Cookie`. `.redirect()` answers a 303; `.json()` answers `{ url }` for a page that navigates itself.                                                                                                                                                                                                          |
+| `callback(request)`                                                       | Checks the signed state (signature, age), that the cookie's nonce matches it, handles `error`, exchanges the code with the PKCE verifier, checks every scope asked for was granted (revoking the grant when one wasn't), seals the refresh token and calls `store`. Always a 303 back to `returnTo` with `?connect=<result>`, clearing the cookie. |
+| `accessToken(sealed, aad)`                                                | A fresh access token, cached in memory until a minute before it expires.                                                                                                                                                                                                                                                                           |
+| `refresh(sealed, aad, { onRotate })`                                      | Uncached; when the provider rotates the refresh token, the new one comes back sealed.                                                                                                                                                                                                                                                              |
+| `revoke(sealed, aad)`                                                     | Revokes at the provider and forgets the cached token. True when it is gone. Google ends every token of the person's grant to your client, so only revoke the last connection that uses it.                                                                                                                                                         |
 
 `accessToken`, `refresh` and `revoke` throw a `ConnectError` (check with `isConnectError(e)`)
 with a `code`: `revoked` (the grant is gone, `invalid_grant`: connect again), `unavailable`
@@ -162,6 +223,15 @@ const token = await connector.accessToken(row.refresh_token, aad, {
   (`redirect: "error"`) and time out after 10 seconds. `log` gets safe lines only: a step, a
   result and a reason such as `token endpoint answered 400 (invalid_grant)`.
 - **`returnTo` is a path**, never a full URL, so the way back can't be pointed elsewhere.
+- **A turned-down grant can be revoked.** When the callback refuses a grant after trading the
+  code (a scope unticked, or no identity with `requireIdentity`), `revokeFailedGrants: true`
+  revokes it through `revokeUrl` (best effort) rather than leave it standing. It's off by
+  default: 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. Turn
+  it on only when each grant is isolated (one connection per client). The revoke runs in the background (at most
+  3 seconds), so it never delays the redirect.
+- **A `store` that throws keeps its grant.** The callback ends as `failed` but doesn't revoke
+  the refresh token, since `store` may have half-written the row; clean up in `store` itself.
 
 ### One callback origin for many addresses
 
@@ -225,5 +295,8 @@ const acme: OAuthProvider = {
 | `fallbackPath`                                 | `/`                             | Where `expired` goes when there is no state to read `returnTo` from.                        |
 | `aad(id)`                                      | `<provider id>-grant:<id>`      | The associated data a grant's refresh token is sealed to.                                   |
 | `requireRefreshToken`                          | true                            | Fail when the provider sends none.                                                          |
+| `requireIdentity`                              | false                           | Fail when no checked `identity` can be read from the ID token (the reason is logged).       |
+| `trustedAudiences`                             | none                            | Other audiences an ID token's `aud` may name besides `clientId`.                            |
+| `revokeFailedGrants`                           | false                           | Revoke a grant the callback turns down (a missing scope, no identity). See below.           |
 | `isPublicSuffix(domain)`                       |                                 | A Public Suffix List lookup for the `sharedDomain` check.                                   |
 | `fetch`, `timeoutMs`, `now`, `randomId`, `log` |                                 | For tests and logging.                                                                      |

package/dist/index.cjs

@@ -8,6 +8,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",
@@ -34,8 +35,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"
 };
@@ -80,6 +87,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(chunkEUEVGKB6_cjs.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",
@@ -138,6 +189,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(
@@ -174,6 +240,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;
@@ -243,6 +310,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",
@@ -312,6 +381,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 {
@@ -562,6 +646,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,
@@ -594,6 +718,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 = chunkEUEVGKB6_cjs.randomToken(16);
       const verifier = chunkEUEVGKB6_cjs.randomToken(32);
       const state = await signState({
@@ -697,8 +826,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,
@@ -708,6 +839,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();
@@ -722,7 +867,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,
@@ -733,7 +879,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);
@@ -762,39 +908,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);
     }
   };
 }