Skip to content

armgit / crm

Public Imported from GitHub
0

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.example
index 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.md
index 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. That
is the difference between a clone that runs and a clone that makes you read a
table 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 add
to the existing Google provider rather than to a second one, so there is no
extra 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 is
imported: Gmail records the current `historyId` on its first pass and imports