Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
TypeScript
chore(env): update .env.example and environment.md to clarify Google sign-in configuration
Lewis Carhart533da0351056
diff --git a/.env.example b/.env.exampleindex a438f94e..a643dd52 100644--- a/.env.example+++ b/.env.example@@ -21,6 +21,13 @@ BETTER_AUTH_SECRET=""# Subdomains count, so "acme.com" also admits "[email protected]".ALLOWED_SIGN_IN=""+# Google is the sign-in method a clone starts with, and the same client is what+# reads Gmail and Calendar. Set both or neither — half a pair is a sign-in+# button that fails at Google.+#+# Leave them empty only if you sign in with your own identity provider, added+# on Settings → SSO. Then there is no Google button and no mail sync, and the+# sign-in page says as much rather than showing you nothing.GOOGLE_CLIENT_ID=""GOOGLE_CLIENT_SECRET=""diff --git a/docs/environment.md b/docs/environment.mdindex 9335f6cb..9cb2a365 100644--- a/docs/environment.md+++ b/docs/environment.md@@ -46,20 +46,36 @@ frames away as a missing variable. `packages/env/test/root.spec.ts` pins this.## What is required-Five values, and the API refuses to start without them.+Three values, and the API refuses to start without them.| Variable | Why it has no default || --- | --- || `DATABASE_URL` | `docker compose up -d` starts a Postgres that matches `.env.example` exactly || `BETTER_AUTH_SECRET` | Signs session cookies. `openssl rand -base64 32` || `ALLOWED_SIGN_IN` | The entire authorisation model — see below |-| `GOOGLE_CLIENT_ID` | Google is the only sign-in method |-| `GOOGLE_CLIENT_SECRET` | |Everything else has a working localhost default or is genuinely optional. Thatis the difference between a clone that runs and a clone that makes you read atable of variables first.+### Google is the fourth value, and it is a pair++`GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are what a clone starts with, and+almost every install wants them: they are both the sign-in button and the Gmail+and Calendar sync. They are nonetheless **optional**, because an install that+signs in through [its own identity provider](./api.md#sso-is-a-row-not-a-deployment)+should not have to create a Google Cloud project to do it.++- **They are set together or not at all.** `packages/auth/src/env.ts` throws on+ one without the other, because half a client is a sign-in button that fails at+ Google with an error the reader cannot act on.+- **Neither Google nor a provider is a state the sign-in page reports**, naming+ the two variables — see [the SSO rules](./api.md#sso-is-a-row-not-a-deployment).+ It is the one configuration mistake whose audience is the person who can fix+ it, so it must not present as a blank page.+- **Without them, Gmail sync is a capability the install does not have**, and+ Settings → Connections says so rather than offering a button that cannot work.+### `ALLOWED_SIGN_IN`Who may sign in, comma-separated, each entry either a whole email domain or a@@ -163,10 +179,32 @@ Always on. Same OAuth client, same callback — the two read-only scopes are addto the existing Google provider rather than to a second one, so there is noextra redirect URI to register.-The scopes are requested **at sign-in** and are a condition of using the CRM:-`requireGoogleAccess()` gates the app shell on what Google actually granted,-because granular consent lets a user untick a scope and still complete sign-in.-Anyone missing either scope is sent to `/grant-access` to re-consent.+The scopes are requested **at sign-in** and are a condition of using the CRM+*for the person who signed in with Google*: `requireGoogleAccess()` gates the+app shell on what Google actually granted, because granular consent lets a user+untick a scope and still complete sign-in. Anyone missing either scope is sent+to `/grant-access` to re-consent.++**Someone who signed in through an identity provider is not gated**, and the+distinction is the whole of `needsGoogleGrant` in+[`@crm/auth`](../packages/auth/src/scopes.ts): the wall applies to an account+whose only sign-in row is `google`. Two reasons it cannot be "does this person+have the scopes".++- **An SSO rep has no Google account to grant them on.** Sending them to+ `/grant-access` is sending them to a page whose only other button is *sign+ out* — a locked door with a sign on it, on an install that may have no Google+ client at all.+- **Linking Gmail must not become a trap.** An SSO rep who connects Google and+ later revokes it would, under a scopes-only rule, be locked out of the CRM by+ having tried the optional feature. `revoke()` clears the tokens and keeps the+ `account` row, so that row is exactly what a scopes-only rule would trip over.++They connect it from **Settings → Connections** instead, which posts the same+`linkSocial` call `/grant-access` does — one write path, two doors. The card+tells the three states apart, because they need three different sentences: no+Google client on the install, a client but no linked account, and a linked+account that has stopped working.**Sync is forward-only.** Nothing from before a mailbox was first seen isimported: Gmail records the current `historyId` on its first pass and imports