Skip to content

fix(cli): complete session-local logout and document auth flows - #1044

Merged
softmarshmallow merged 3 commits into
mainfrom
chore/auth-flow-blueprint
Sep 10, 2026
Merged

softmarshmallow merged 3 commits into
mainfrom
chore/auth-flow-blueprint

Conversation

@softmarshmallow

@softmarshmallow softmarshmallow commented Sep 10, 2026 •

Copy link
Copy Markdown
Member

CLI logout clears local credentials but can leave remote revocation unconfirmed: its issuer logout request omits the public project admission key, and it cannot revoke an expired access session. This fixes the endpoint contract and logout lifecycle, with a cross-client auth blueprint explaining credential ownership and logout scope.

  • Bundle the existing public project key in explicit CLI registration and send it only to the fixed issuer logout endpoint. Key rotation preserves existing account profiles.
  • Clear local custody first. Near expiry, refresh once in memory, require the captured issuer/user/client/session binding, verify live identity, then revoke only that session. Never persist renewed credentials or overwrite a newer login. Confirm only completed 200/204 responses and discard logout bodies.
  • Extend existing transport, custody, browser and installed-CLI proofs. The local gateway is more permissive than hosted admission, so the required header is asserted explicitly.
  • Document web/Desktop/CLI/provider flows, register SEC015 for account-to-media credential separation, update SEC010/011, and correct inaccurate HttpOnly wording without changing cookie policy. Prepare stable grida@0.1.0 for npm latest, with plain npm install -g grida instructions and the matching documentation guard.

The cause is an integration-contract gap: successful OAuth token exchange and permissive local logout did not prove hosted logout admission. No database migration, new server endpoint, or production setting change is introduced. Web/Desktop logout scope is unchanged.

Validation: 444 auth tests passed (one opt-in real-keyring smoke skipped), 422 CLI tests passed, 52 repository typecheck tasks passed, guard/release tests passed, and all-locale docs build plus installed docs checks passed. Stable release metadata and the corresponding install-example guard also passed focused release/docs checks. Real local OAuth and the final packed CLI prove revocation and preservation of other sessions. Expiry coverage uses synthetic issuer expiry enforcement and explicitly bounded client-clock advancement against real local Auth; hosted installed acceptance remains a release gate.

Ready for peer review. No production mutation or npm publication has been performed.

@vercel

vercel Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs Ready Ready Preview Sep 10, 2026 11:48am UTC
grida Ready Ready Preview Sep 10, 2026 11:48am UTC
4 Skipped Deployments
Project Deployment Actions Updated
backgrounds Ignored Ignored Preview Sep 10, 2026 11:48am UTC
blog Ignored Ignored Preview Sep 10, 2026 11:48am UTC
code Ignored Ignored Sep 10, 2026 11:48am UTC
viewer Ignored Ignored Preview Sep 10, 2026 11:48am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 3e3ed82f-d883-44d5-ac5a-c3aab3ffa21b

📥 Commits

Reviewing files that changed from the base of the PR and between 216b06c and 21a7364.

📒 Files selected for processing (47)
  • .github/workflows/cli-release.yml
  • SECURITY.md
  • desktop/README.md
  • desktop/src/main/desktop-entry-window.ts
  • docs/cli/auth.md
  • docs/cli/flutter-daemon.md
  • docs/cli/index.md
  • docs/reference/authentication.md
  • docs/reference/index.md
  • docs/wg/cli/account-infrastructure.md
  • docs/wg/cli/documentation.md
  • docs/wg/cli/v1.md
  • docs/wg/platform/index.md
  • editor/e2e/auth-oauth.spec.mts
  • editor/lib/api/gg.test.ts
  • editor/lib/auth/README.md
  • editor/lib/auth/__tests__/oauth-bearer.test.ts
  • editor/lib/auth/bearer.ts
  • editor/lib/gg/tokens.test.ts
  • editor/lib/gg/tokens.ts
  • packages/grida-auth/README.md
  • packages/grida-auth/src/auth-client.test.ts
  • packages/grida-auth/src/auth-client.ts
  • packages/grida-auth/src/credential-store.test.ts
  • packages/grida-auth/src/node.test.ts
  • packages/grida-auth/src/node.ts
  • packages/grida-auth/src/persistent-auth.test.ts
  • packages/grida-cli/README.md
  • packages/grida-cli/package.json
  • packages/grida-cli/src/commands/auth.test.ts
  • packages/grida-cli/src/host.test.ts
  • packages/grida-cli/src/host.ts
  • packages/grida-cli/src/media-run.test.ts
  • packages/grida-cli/src/media-run.ts
  • packages/grida-cli/src/oauth-client-registration.ts
  • scripts/auth-local/README.md
  • scripts/auth-local/native-probe.mjs
  • scripts/auth-local/stack.mjs
  • scripts/cli-docs/README.md
  • scripts/cli-docs/check.mjs
  • scripts/cli-docs/check.test.mjs
  • scripts/cli-local/README.md
  • scripts/cli-local/linux-smoke.mjs
  • scripts/cli-local/proof.mjs
  • scripts/cli-media-local/proof.mjs
  • scripts/cli-release/README.md
  • scripts/cli-release/prepare.test.mjs

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.


Walkthrough

The change updates native logout to use session-bound validation, detached renewal, publishable-key admission, and strict revocation confirmation. It adds CLI and persistent-auth coverage, documents authentication boundaries, and changes CLI release guidance from the preview channel to stable 0.1.0.

Changes

Authentication and CLI release

Layer / File(s) Summary
Session-local logout contract and implementation
packages/grida-auth/src/auth-client.ts, packages/grida-auth/src/node.ts, packages/grida-auth/src/*test.ts
Logout validates JWT session claims, clears custody before remote work, performs detached renewal when required, sends the publishable key only to local logout, and confirms only HTTP 200 or 204 responses.
Persistent expiry and concurrency validation
packages/grida-auth/src/persistent-auth.test.ts
Persistent-auth tests cover clock-injected expiry, token rotation, issuer validation, and protection against stale logout completion overwriting newer sessions.
CLI registration and logout integration
packages/grida-cli/src/*, scripts/auth-local/*, scripts/cli-local/*, editor/e2e/auth-oauth.spec.mts
CLI registration requires the publishable key. CLI and end-to-end proofs verify logout headers, expired-session renewal, token revocation, and independent session preservation.
Security boundaries and authentication blueprint
SECURITY.md, docs/reference/authentication.md, desktop/*, editor/lib/auth/*, editor/lib/gg/*
Security records and reference documentation describe cookie handling, credential ownership, logout scope, publishable-key admission, and account-to-media separation.
Stable CLI 0.1 release documentation
.github/workflows/cli-release.yml, packages/grida-cli/package.json, docs/cli/*, docs/wg/cli/*, scripts/cli-docs/*, scripts/cli-release/*
Release configuration and documentation use stable CLI 0.1.0 with the latest tag. Prereleases continue to use next.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant AuthClient
  participant CredentialStore
  participant SupabaseIssuer
  CLI->>AuthClient: auth logout
  AuthClient->>CredentialStore: clear local custody
  AuthClient->>SupabaseIssuer: detached refresh if session is near expiry
  AuthClient->>SupabaseIssuer: verify identity
  AuthClient->>SupabaseIssuer: POST /logout?scope=local with Bearer and apikey
  SupabaseIssuer-->>AuthClient: 200 or 204
  AuthClient-->>CLI: confirmed revocation and signed-out status
Loading

Merge Risk: ⚪ Minimal · up to 21a73

The session-local logout and stable CLI release changes are ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 4.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 27 files. (20 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main changes: completing session-local CLI logout and documenting authentication flows.
Description check ✅ Passed The description directly explains the logout fixes, authentication documentation, testing, release preparation, and scope limitations covered by the changeset.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 4.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 27 files. (20 skipped: 20 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/auth-flow-blueprint

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@softmarshmallow
softmarshmallow marked this pull request as ready for review September 10, 2026 11:43
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-10T11:50:14.996715Z 21a7364 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

This branch was successfully deployed

2 active deployments
Preview – grida — 21a73645 Deployed Sep 10, 2026 by vercel[bot]
Preview – docs — 21a73645 Deployed Sep 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant