macOS: Granola DEK is entitlement-gated; grans must own its own credentials

[dmwyatt]

Summary

grans sync is broken on current macOS Granola builds and cannot be fixed by improving our decryption code. Granola now stores its data-encryption key (DEK) in the macOS data-protection keychain, gated on Granola's own code signature and team ID. No third-party process can read it, with or without a user prompt.

The fix is for grans to stop scavenging Granola's local storage on macOS and instead hold its own credentials.

This is the follow-up to #86 / PR #88, which implemented the Windows os_crypt scheme and assumed macOS matched it.

Reproduction

$ grans sync
[grans] Starting full sync from Granola API...
Error: Failed to read encrypted Granola token store in /Users/<user>/Library/Application Support/Granola

Caused by:
    0: Failed to read the 'Granola Safe Storage' password from the macOS Keychain. Ensure Granola is installed and allow access when prompted, or pass --token.
    1: The specified item could not be found in the keychain.

Granola desktop 7.441.6, macOS.

What we found

1. Three distinct defects, only one of them trivial

Assumption in src/api/token_store.rs	Reality on macOS
Keychain account is Granola	Account is Granola Key (service Granola Safe Storage)
storage.dek exists	File does not exist
Local State has an os_crypt master key	Contains only {"uninstall_metrics":{...}}
supabase.json.enc is v10-prefixed	No prefix: [12-byte nonce][ciphertext][16-byte GCM tag]

Fixing the account name alone changes nothing, because there is no storage.dek to unseal.

2. The DEK is entitlement-gated

From /Applications/Granola.app/Contents/Resources/app.asar and the bundled native/keychain.node:

• On packaged macOS builds Granola calls getOrCreateDek() in its native module.
• The DEK is a random 32 bytes stored in the data-protection keychain:
  • service com.granola.app.dek
  • access group QZ7DHHLN25.granola
  • kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
  • kSecUseDataProtectionKeychain
• On upgrade it migrates any legacy storage.dek via safeStorage.decryptStringAsync → importDek(buf) → then unlinkSyncs the file. That is why it is missing.

A direct SecItemCopyMatching probe confirms this empirically:

Query	Result
service com.granola.app.dek + access group QZ7DHHLN25.granola	errSecMissingEntitlement
same, without access group	errSecItemNotFound

Access requires an entitlement bound to Granola's code signature. This is not something a prompt, an admin password, or better Rust can work around.

Non-darwin and unpackaged builds still use the old storage.dek + safeStorage path, so the Windows implementation remains correct and should be preserved.

3. Every other local route is closed

• granola.db — SQLCipher; random header, sqlite3 reports "file is not a database".
• cache-v6.json.enc, stored-accounts.json.enc, user-preferences.json.enc — same DEK.
• Electron Local Storage/leveldb — only a feature-flag string, no JWT.
• No Granola process listening on any local TCP port.
• Leftover plaintext supabase.json (May 7) and stored-accounts.json (Jun 12) are stale; every live file was rewritten encrypted on Jul 25.

We deliberately did not try the stale refresh token. WorkOS rotates refresh tokens and treats replay of a consumed one as compromise, revoking the whole session family — it would likely log the user out of Granola desktop.

4. There is no Granola web app

Worth recording, since it is an easy wrong turn:

• https://notes.granola.ai/ → 308 → marketing site.
• https://app.granola.ai/, https://app.granola.so/ → do not resolve.
• The desktop client only parses notes.granola.ai for share links: /d/<id>, /f/<id>, /t/<slug>.

So there is no browser session to copy a token from.

The path forward

grans should own its own credentials. Granola's desktop login is standard PKCE and is fully replicable.

Login (verified live)

GET https://api.granola.ai/v1/auth
    ?dev=false
    &code_challenge=<base64url(SHA-256(verifier)), padding stripped>
    &platform=macOS
    &version=7.441.6
    &sign_in_click_id=<uuid>
    &intent=download
    &provider=google        # or microsoft

→ 302 to https://api.workos.com/user_management/authorize?client_id=client_01JZJ0XBDAT8PHJWQY09Y0VD61&...

Notes:

• Omitting version returns 302 to https://granola.ai/upgrade-app. The client version is mandatory and will need periodic bumping.
• PKCE verifier is 43 chars over [A-Za-z0-9-._~], challenge is S256.

Callback

Browser lands on granola://login-complete?code=<code>&..., validated against:

{ code, isDev?, sso?, handoff?, signInClickId?, inAppCalendarLinking?, calendarLinkingFlow? }

Exchange

POST https://api.granola.ai/v1/workos-auth-complete
{ code, codeVerifier, platform, isDev, sso, ssoCode, signInClickId, ... }

In the bundle this is k(null, 'workos-auth-complete', ...). The null first argument means the call is unauthenticated, which is what makes bootstrap possible. It returns the workos_tokens object including refresh_token.

Refresh (indefinite)

async function Li(e, t, n) {            // e = access token, t = refresh token
  return Pi(e, `refresh-access-token`, {
    input: { refresh_token: t }, retries: 3, signal: n.signal,
    additionalHeaders: n.timeZone ? { "X-Granola-Time-Zone": n.timeZone } : undefined
  });
}

POST https://api.granola.ai/v1/refresh-access-token
Authorization: Bearer <access token>
{ "refresh_token": "..." }

Response schema is {access_token, expires_in, refresh_token, token_type, obtained_at?, session_id?, sign_in_method?} — it returns a rotated refresh_token which must be persisted on every refresh, or the chain breaks.

This keeps the full internal API surface grans already depends on: v2/get-documents, v1/get-document-transcript, v1/get-document-panels, people, calendars, templates, recipes.

Open problem: intercepting the callback

macOS routes granola:// to Granola.app, so grans cannot receive the code directly.

We tried the obvious fix — redirect=http://127.0.0.1:<port>/callback on /v1/auth — and it returns 403. The parameter exists but is server-side gated to Granola's own web shell, so the standard loopback CLI pattern is unavailable.

Candidate approaches, in descending order of preference:

1. Manual paste. grans prints the auth URL; user completes login and pastes the granola://login-complete?... URL back. Reliable and reversible, but awkward — browsers show an app-open prompt rather than the target URL.
2. granola-dev:// scheme. The URL parser accepts granola-dev: as well as granola:, and Info.plist registers only granola. grans could claim granola-dev:// with no conflict. Unverified: dev=true may switch to a staging backend holding none of the user's data. Must be confirmed before relying on this.
3. Temporarily reassign the granola:// handler via LSSetDefaultHandlerForURLScheme, then restore. Rejected — an interrupted run would leave the user unable to log into Granola at all.

There is no device/polling flow to sidestep this: login-check and auth-handoff-complete appear only in the endpoint table and are never called by the client, and retrieve-device-session requires an existing access token.

Decision required before implementation

Performing this login means grans presents Granola's platform and version against Granola's own WorkOS client ID — i.e. it authenticates as the first-party desktop client. It is the user's own account and own data, and grans already calls the internal API, but minting new sessions is a step beyond reading a token the app had already stored. This should be an explicit decision, not an implicit one.

Alternative: the sanctioned public API

Granola ships an official public API (https://public-api.granola.ai, grn_ keys, created in Settings → Connectors → API keys; the revoke-public-api-key endpoint confirms the feature).

• Pros: sanctioned, stable, workspace keys never expire.
• Cons: only /v1/notes, /v1/notes/{id}?include=transcript, /v1/folders. No panels, people, calendars, templates or recipes. Requires a Business/Enterprise plan.

A poor fit for grans today, but worth revisiting as an optional backend.

Proposed implementation

1. src/api/credentials.rs — new credential store modelled on the existing src/sync/config.rs Dropbox pattern: TOML at data_dir()/auth.toml, atomic temp-file write + rename, 0600 on unix. Fields: refresh_token, access_token, expires_at, session_id.
2. src/api/auth.rs — refresh_access_token(...); persist the rotated refresh token before returning so a crash cannot strand the chain.
3. grans auth login / status / logout — PKCE generation, browser launch, callback capture, code exchange. login also accepts a refresh token on stdin so it never lands in shell history. status prints only expiry and presence, never token material.
4. resolve_token resolution order — --token → GRANS_TOKEN env var → stored credentials (refresh if expired) → Granola's local store. The last step is unchanged, so Windows and older/unpackaged macOS builds keep working. Note the crate is edition 2024, so env::set_var is unsafe; keep the env read at the CLI boundary and pass an Option<String> down to keep tests free of environment mutation.
5. src/api/token_store.rs — keep the Granola Key / Granola account fallback and the storage.dek-existence check that avoids a pointless Keychain prompt. Add a typed marker error so read_token_json can downcast_ref and surface actionable guidance directly instead of burying it under Caused by:.
6. Docs — README.md (~123-136) currently claims the macOS Keychain prompt works; correct it. Update CLAUDE.md:61. Note that scripts/granola-token.py is Windows-only.

Risks

• grans creates its own session, visible in Granola's session list and revocable there.
• Hardcoded client version will eventually trip the upgrade-app redirect.
• Refresh-token rotation must be persisted atomically on every refresh.
• Do not replay the stale refresh token from the old plaintext supabase.json.

[dmwyatt]

Review notes on the credential-ownership approach

The empirical grounding here is solid (the asar inspection plus the SecItemCopyMatching probes that separate errSecMissingEntitlement from errSecItemNotFound settle that the DEK is signature-gated and unreachable). Agreeing with the pivot. Some additions and course-corrections for implementation.

On the decision it asks for: proceed with the PKCE flow

grans already rides the internal API with first-party credentials, so minting a session is an incremental step rather than a category change. It is the user's own account, the session is visible and revocable in Granola's session list, and the volume is a single CLI. The residual risks are breakage-shaped (version gating, possible future attestation), not safety-shaped, and they fail loudly. Worth acknowledging the ToS gray area once, deciding, and moving on.

This is not only a macOS fix

Granola's native keychain module already migrated macOS to the entitlement-gated DEK and deleted storage.dek. There is no reason the same migration will not reach Windows eventually (DPAPI/CNG has an equivalent story). Owning credentials future-proofs both platforms and demotes local-store scavenging to a legacy fallback, which the proposed resolution order (--token -> env -> stored credentials -> local store) already expresses. Worth stating that intent explicitly so nobody later "simplifies" the Windows path by removing the fallback chain.

Refresh with an expired access token is not a risk

Correcting an earlier worry of mine. Granola can sit closed for weeks and then refresh on launch without forcing re-login, which is direct proof the refresh-access-token endpoint accepts an expired access token. That launch-after-idle state is exactly an expired access token plus a stored refresh token. The Authorization: Bearer <access token> on the call is for identification; the grant being validated is the refresh_token in the body. grans inherits this by making the same call.

This matters more than it looks: after initial login grans holds its own independent session and refresh-token chain, separate from Granola desktop's. So post-login grans does not depend on Granola being open, running, or even installed. An expired access token simply means "refresh on next run." I would still run one expired-token refresh as a cheap confirmation while wiring up the credential store, but as a sanity check, not a gate.

The real long-idle limit is the refresh token's absolute lifetime

WorkOS refresh tokens can carry a hard absolute expiry (for example a 90-day cap), after which even the refresh grant is dead and re-login is required. This hits Granola identically: leave it long enough and it logs you out too. The correct handling is to detect a failed refresh and print "run grans auth login again," a loud recoverable message rather than silent breakage.

Refresh rotation plus concurrency needs single-flight

"Persist the rotated refresh token before returning" is necessary but not sufficient. Two concurrent invocations (a manual sync racing a scheduled one) can both attempt a refresh; one rotates the token, the other's refresh fails against a now-consumed token, and a naive implementation could then persist the stale value and strand the chain. Needs:

• a file lock around the refresh so only one invocation refreshes at a time, and
• a retry that re-reads the credential store before declaring the chain broken (the other invocation may have just written a fresh token).

granola-dev:// has a hidden cost on macOS

URL schemes are claimed by app bundles via CFBundleURLTypes, not by CLI binaries. grans would have to ship and register a helper .app to receive granola-dev:// callbacks. Combined with the unverified dev=true staging-backend risk already noted, that settles the ordering: manual paste first, scheme capture only as later UX polish if ever.

Manual-paste UX: tell the user to cancel the app-open dialog

The auth code is PKCE-bound to the verifier grans generated. If the user clicks "Open Granola" on the browser's app-open prompt, Granola's own exchange fails harmlessly but may consume the code, leaving grans with a dead code and a confusing error. The auth login instructions should say explicitly: cancel the app-open dialog, then copy the granola://login-complete?... URL.

Make the spoofed client version an override, not just a constant

The hardcoded version will eventually trip the upgrade-app redirect. Expose it as a config value / env var (for example GRANS_GRANOLA_VERSION) so the fix is a one-line user workaround rather than a required release. Detect that specific redirect on the auth and refresh paths and surface "bump GRANS_GRANOLA_VERSION" instead of a generic auth failure.

Credential storage: TOML now, platform keychain as a follow-up

Starting with auth.toml for consistency with the Dropbox src/sync/config.rs pattern is the right call. Two notes: the 0600 protection is a no-op on Windows, so the file-encryption story there is nothing (the token sits in plaintext under the user profile). A later option is storing grans's own refresh token in the platform keychain. grans would be the creator of its own item, so there is no entitlement problem, unlike reading Granola's. Worth a follow-up issue rather than scope creep here.

Suggested sequencing

The size: l decomposes cleanly into sub-issues:

1. Credential store + refresh chain (with single-flight) + resolve_token resolution order. Bootstrappable by pasting a refresh token on stdin, no login UI yet. This milestone alone un-bricks macOS.
2. grans auth login with the manual-paste PKCE flow.
3. Docs correction (README ~123-136, CLAUDE.md:61) and the typed marker error in token_store.rs.

Happy to break these out as tracked sub-issues if useful.