@marktiderman/genesis-connect 0.2.0 → 0.3.0

package/README.md

@@ -112,19 +112,27 @@ export const googleCalendar = createConnector({
 });
 ```
 
-`identity` is read from the ID token the token endpoint sent over TLS. 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 is this client, and it
-hasn't expired. When any of those fail (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. `email` is there only when the provider says
+`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: until Google verifies the app, only its test users can connect,
-and their grants end after seven days.
+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
 
@@ -164,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`
@@ -215,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
 
@@ -279,5 +296,7 @@ const acme: OAuthProvider = {
 | `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

@@ -109,7 +109,12 @@ function identityFromTokenEndpoint(idToken, expect) {
   const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
   if (!audiences.includes(expect.clientId))
     return { reason: "audience mismatch" };
-  if (audiences.length > 1 && claims["azp"] !== expect.clientId)
+  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)
@@ -184,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(
@@ -220,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;
@@ -289,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",
@@ -358,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 {
@@ -608,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,
@@ -640,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({
@@ -743,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,
@@ -755,16 +840,19 @@ ${refreshToken}`);
         );
       }
       const idToken = typeof body["id_token"] === "string" ? body["id_token"] : void 0;
-      const issuer = config.provider.issuer;
-      const read = idToken ? identityFromTokenEndpoint(idToken, {
-        issuers: typeof issuer === "string" ? [issuer] : issuer ?? [],
+      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 (is openid asked for?)" };
-      const identity = "subject" in read ? read : void 0;
-      const identityNote = "reason" in read ? `no identity: ${read.reason}` : void 0;
-      if (!identity && config.requireIdentity)
+      }) : { 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();
@@ -820,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);
     }
   };
 }