[add-resource] New Plugin: Google Drive Auth (gdrive-auth)

[sandymac]

Please add this plugin to GPM.

• Name: Google Drive Auth
• Slug: gdrive-auth
• Repository: https://github.com/sandymac/grav-plugin-gdrive-auth
• Release: 1.0.0 (bare tag, matches version: in blueprints.yaml)
• License: MIT
• Docs: https://github.com/sandymac/grav-plugin-gdrive-auth/blob/main/README.md
• Compatibility: grav: ['2.0']; dependencies grav >=2.0.23, api >=1.0.41, admin2 >=2.1.24; PHP 8.3+
• Install zip: the release asset gdrive-auth-1.0.0.zip (git archive of the tag, dev files stripped), SHA-256 79d292ec630d2d60b2df6d391e365ee529a0fa73b148d0249a6c5031e3e180a2

What it does: Google sign-in for a Grav 2 Google Drive plugin family. A site connects a Google account once, either as an OAuth user through its own Google Cloud "Web application" client (PKCE S256, offline access, revoke) or as a service account (RS256 JWT signed with openssl_sign), and plugins built on it call Gdrive::drive($account, $scopes) for a thin Drive v3 client (Shared Drives on every call, 401 → refresh-once, backoff on 429/5xx, resumable single-PUT upload). Dependent plugins declare the account and scopes they need through an onGdriveScopes event; an OAuth account that hasn't granted a scope is refused with scope_not_granted.

The Admin2 settings page (two custom fields plus server-rendered display fields) has a guided setup that asks a few questions and shows only the steps that apply, an Accounts tab (add by upload or paste, Test, Connect in a popup, Remove) and full OAuth, service-account and Troubleshooting guides with the site's redirect URI, service-account emails and needed scopes filled in. Its routes live under /api/v1/gdrive behind a dedicated api.gdrive.manage permission; the public OAuth callback at /gdrive-oauth/callback is the only front-end route. No Composer dependencies: curl and openssl only.

Security notes (SECURITY.md has the full list): credentials live only in user/data/gdrive/auth/, written atomically with mode 0600, never in config, logs or API responses; account names are validated before any path is built and uploaded JSON is shape-checked; sign-in and token requests go only to Google's own endpoints whatever an uploaded file says; the callback trusts a single-use, 10-minute, server-side state (32 random bytes stored by SHA-256) plus PKCE and answers a generic 400 otherwise, with the reason logged; the redirect URI follows system.custom_base_url and Google exact-matches it, so a forged Host header goes nowhere; the callback page sends a nonce CSP, X-Frame-Options: DENY, Cache-Control: no-store and Referrer-Policy: no-referrer.

Testing: tests/smoke.php (fake transports, no network: JWT, PKCE, state single-use and expiry, scope enforcement, retry and 401 logic, upload request shape, pinned endpoints, credential and name validation, the settings page's rows and guides, a Troubleshooting anchor for every reason code, version drift), PHPStan level 6 against Grav 2.0.23 / api 1.0.41 and Grav 2.2.4 / api 1.0.44, PHP 8.3 and 8.4, all in CI. Clicked through on a production site running Grav 2.2.4, api 1.0.44, admin2 2.1.27, PHP 8.3: every tab renders, Test passes against Drive.

Note: the two plugins built on it (gdrive-images, gdrive-backup) are still private and will be submitted separately once they're ready, so the README's links to them don't resolve yet.

[rhukster]

Thanks @sandymac, this is a careful submission. I went through the 1.0.0 tag and installed it on a clean Grav 2.2.4 site. The settings page renders, every /api/v1/gdrive route refuses anonymous and non-gdrive users, uploads with a non-Google token_uri or auth_uri are refused, the callback gives a plain 400 without a valid state, and the user/data/gdrive/auth/ files are blocked by the stock server rules. Nice work on the state handling and the callback headers.

I'll get gdrive-auth added to GPM. A few small things you may want for a 1.0.1, none of them blocking: the account-name regex lets a trailing newline through (use \z or the D flag), the window.confirm fallback in gdrive-accounts.js can go now that you require admin2 2.1.24, and the redirect URI is only pinned when custom_base_url is set, so it's worth saying that in the docs as you already do in SECURITY.md.

[sandymac]

Thanks @rhukster, all three are in 1.0.1:

1. Trailing newline. Accounts::NAME, the OAuth-state check and Setup::PROJECT_ID now carry the D modifier. Smoke covers each: a name with a trailing newline is refused by saveCredential() and by the request-body check, a project ID with one by guideProfile(), and a state with one by finishConnect() without consuming the real state file. The same smoke file run against a copy with the D modifiers removed fails on the first of those.
2. window.confirm fallback removed; Remove uses __GRAV_DIALOGS.confirm only.
3. Redirect URI. The README and the OAuth guide's redirect-URI step now say it follows system.custom_base_url when set and the current request otherwise, so sites behind a proxy or CDN know to set it.

The install zip is attached to the release by the release-asset workflow: gdrive-auth-1.0.1.zip, SHA-256 9d0acba0ee16d6b9a19207642191a45689008c0aca5790aafbdde0d34ff9dbba. Thanks for the thorough review.