@marktiderman/genesis-connect 0.1.3 → 0.2.0

package/dist/index.d.cts

@@ -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) and a
+     * provider with an `issuer`; left out when the token's issuer, audience 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,12 @@ 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;
     /**
      * 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 +342,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.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) and a
+     * provider with an `issuer`; left out when the token's issuer, audience 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,12 @@ 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;
     /**
      * 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 +342,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,45 @@ 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.length > 1 && claims["azp"] !== expect.clientId)
+    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",
@@ -707,6 +753,17 @@ ${refreshToken}`);
           "no refresh token (is offline access asked for?)"
         );
       }
+      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 ?? [],
+        clientId: config.clientId,
+        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)
+        return back(request, state, "failed", {}, identityNote);
       let extra;
       try {
         const id = config.randomId?.() ?? crypto.randomUUID();
@@ -721,7 +778,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 +790,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);