@ssheleg/sheleg-dev 0.4.0

package/plugins/sheleg-dev/skills/google-auth/references/workload-identity.md

@@ -0,0 +1,376 @@
+# Workload & Workforce Identity Federation (Node.js & Python)
+
+
+## Contents
+
+- [Table of Contents](#table-of-contents)
+- [Overview](#overview)
+- [AWS Federation](#aws-federation)
+- [Azure Federation](#azure-federation)
+- [OIDC Provider Federation](#oidc-provider-federation)
+- [Custom Subject Token Supplier](#custom-subject-token-supplier)
+- [Workforce Identity Federation](#workforce-identity-federation)
+- [Executable-Sourced Credentials](#executable-sourced-credentials)
+- [Using External Identities](#using-external-identities)
+- [Configurable Token Lifetime](#configurable-token-lifetime)
+- [Security Considerations](#security-considerations)
+
+## Table of Contents
+- [Overview](#overview)
+- [AWS Federation](#aws-federation)
+- [Azure Federation](#azure-federation)
+- [OIDC Provider Federation](#oidc-provider-federation)
+- [Custom Subject Token Supplier](#custom-subject-token-supplier)
+- [Workforce Identity Federation](#workforce-identity-federation)
+- [Executable-Sourced Credentials](#executable-sourced-credentials)
+- [Using External Identities](#using-external-identities)
+- [Configurable Token Lifetime](#configurable-token-lifetime)
+- [Security Considerations](#security-considerations)
+
+## Overview
+
+Workload Identity Federation lets non-GCP workloads (AWS, Azure, OIDC/SAML providers) access Google Cloud without service account keys. It works by exchanging an external token for a short-lived GCP access token via the Security Token Service (STS).
+
+Benefits:
+- No service account key management
+- No key rotation needed
+- Short-lived credentials only
+- Works across cloud providers
+
+## AWS Federation
+
+### Setup
+
+1. Create a workload identity pool
+2. Add AWS as identity provider
+3. Grant `roles/iam.workloadIdentityUser` to external identity
+4. Generate credential configuration:
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AWS_PROVIDER_ID \
+  --service-account $SERVICE_ACCOUNT_EMAIL \
+  --aws \
+  --output-file /path/to/config.json
+```
+
+### Custom AWS Supplier — Node.js
+
+For non-EC2 environments (ECS, EKS, Fargate):
+
+```ts
+import {AwsClient, AwsSecurityCredentials, AwsSecurityCredentialsSupplier, ExternalAccountSupplierContext} from 'google-auth-library';
+import {fromNodeProviderChain} from '@aws-sdk/credential-providers';
+
+class AwsSupplier implements AwsSecurityCredentialsSupplier {
+  private readonly region: string;
+  constructor(region: string) { this.region = region; }
+
+  async getAwsRegion(context: ExternalAccountSupplierContext): Promise<string> {
+    return this.region;
+  }
+
+  async getAwsSecurityCredentials(context: ExternalAccountSupplierContext): Promise<AwsSecurityCredentials> {
+    const creds = await fromNodeProviderChain()();
+    return {
+      accessKeyId: creds.accessKeyId,
+      secretAccessKey: creds.secretAccessKey,
+      token: creds.sessionToken
+    };
+  }
+}
+
+const authClient = new AwsClient({
+  audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID',
+  subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request',
+  aws_security_credentials_supplier: new AwsSupplier('us-east-1'),
+  service_account_impersonation_url: 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$EMAIL:generateAccessToken',
+});
+```
+
+### Custom AWS Supplier — Python
+
+```python
+from google.auth import aws
+from google.auth import exceptions
+
+class CustomAwsSecurityCredentialsSupplier(aws.AwsSecurityCredentialsSupplier):
+
+    def get_aws_security_credentials(self, context, request):
+        try:
+            # Return valid AWS security credentials.
+            # These are NOT cached by google-auth — implement caching here.
+            return aws.AwsSecurityCredentials(
+                access_key_id=ACCESS_KEY_ID,
+                secret_access_key=SECRET_ACCESS_KEY,
+                session_token=SESSION_TOKEN
+            )
+        except Exception as e:
+            raise exceptions.RefreshError(e, retryable=True)
+
+    def get_aws_region(self, context, request):
+        return 'us-east-1'
+
+supplier = CustomAwsSecurityCredentialsSupplier()
+
+credentials = aws.Credentials(
+    audience='//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID',
+    subject_token_type='urn:ietf:params:aws:token-type:aws4_request',
+    aws_security_credentials_supplier=supplier,
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+## Azure Federation
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$AZURE_PROVIDER_ID \
+  --service-account $SERVICE_ACCOUNT_EMAIL \
+  --azure \
+  --output-file /path/to/config.json
+```
+
+## OIDC Provider Federation
+
+### File-Sourced
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$OIDC_PROVIDER_ID \
+  --service-account $SERVICE_ACCOUNT_EMAIL \
+  --credential-source-file $PATH_TO_OIDC_TOKEN \
+  --output-file /path/to/config.json
+```
+
+### URL-Sourced
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$OIDC_PROVIDER_ID \
+  --service-account $SERVICE_ACCOUNT_EMAIL \
+  --credential-source-url $URL_TO_GET_TOKEN \
+  --credential-source-headers Metadata-Flavor=Google \
+  --output-file /path/to/config.json
+```
+
+## Custom Subject Token Supplier
+
+For OIDC/SAML tokens from custom sources.
+
+### Node.js
+
+```ts
+import {IdentityPoolClient, SubjectTokenSupplier, ExternalAccountSupplierContext} from 'google-auth-library';
+
+class CustomSupplier implements SubjectTokenSupplier {
+  async getSubjectToken(context: ExternalAccountSupplierContext): Promise<string> {
+    // Implement caching — library does not cache
+    const audience = context.audience;
+    const subjectTokenType = context.subjectTokenType;
+    return fetchTokenFromProvider();
+  }
+}
+
+const client = new IdentityPoolClient({
+  audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID',
+  subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+  subject_token_supplier: new CustomSupplier()
+});
+```
+
+### Python
+
+```python
+from google.auth import identity_pool
+from google.auth import exceptions
+
+class CustomSubjectTokenSupplier(identity_pool.SubjectTokenSupplier):
+
+    def get_subject_token(self, context, request):
+        try:
+            # Implement caching — library does not cache external tokens.
+            audience = context.audience
+            subject_token_type = context.subject_token_type
+            return fetch_token_from_provider()
+        except Exception as e:
+            raise exceptions.RefreshError(e, retryable=True)
+
+supplier = CustomSubjectTokenSupplier()
+
+credentials = identity_pool.Credentials(
+    audience='//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID',
+    subject_token_type='urn:ietf:params:oauth:token-type:id_token',
+    subject_token_supplier=supplier,
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+## Workforce Identity Federation
+
+For human users (employees, partners) authenticating via external IdP (Azure AD, Okta, AD FS).
+
+### Generate Config
+
+```bash
+# OIDC
+gcloud iam workforce-pools create-cred-config \
+  locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
+  --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
+  --credential-source-file=$PATH_TO_TOKEN \
+  --workforce-pool-user-project=$PROJECT_NUMBER \
+  --output-file=/path/to/config.json
+
+# SAML
+gcloud iam workforce-pools create-cred-config \
+  locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \
+  --credential-source-file=$PATH_TO_SAML_ASSERTION \
+  --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
+  --workforce-pool-user-project=$PROJECT_NUMBER \
+  --output-file=/path/to/config.json
+```
+
+### Browser-Based Login
+
+```bash
+gcloud auth application-default login --login-config=$LOGIN_CONFIG
+```
+
+Default refresh token lifetime: 1 hour (configurable up to 12 hours via pool session duration).
+
+## Executable-Sourced Credentials
+
+For custom token retrieval via local executable:
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
+  --service-account=$SERVICE_ACCOUNT_EMAIL \
+  --subject-token-type=$SUBJECT_TOKEN_TYPE \
+  --executable-command="/path/to/command --arg=value" \
+  --executable-timeout-millis=30000 \
+  --executable-output-file=/path/to/cached-token.json \
+  --output-file /path/to/config.json
+```
+
+Requires: `export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1`
+
+### Executable Response Format
+
+Success (OIDC):
+```json
+{"version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "HEADER.PAYLOAD.SIGNATURE", "expiration_time": 1620499962}
+```
+
+Error:
+```json
+{"version": 1, "success": false, "code": "401", "message": "Caller not authorized."}
+```
+
+### Environment Variables Set for Executable
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE` | Audience from config |
+| `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL` | SA email (if impersonating) |
+| `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE` | Output file path (if set) |
+| `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE` | Expected subject token type |
+
+## Using External Identities
+
+After generating a config JSON, use with ADC.
+
+### Environment Setup
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json
+```
+
+### Node.js
+
+```js
+const {GoogleAuth} = require('google-auth-library');
+
+const auth = new GoogleAuth({
+  scopes: 'https://www.googleapis.com/auth/cloud-platform',
+  projectId: 'CLOUD_RESOURCE_PROJECT_ID' // avoids needing roles/browser
+});
+const client = await auth.getClient();
+const res = await client.fetch(url);
+```
+
+Or explicit initialization:
+
+```js
+const {ExternalAccountClient} = require('google-auth-library');
+const jsonConfig = require('/path/to/config.json');
+
+const client = ExternalAccountClient.fromJSON(jsonConfig);
+client.scopes = ['https://www.googleapis.com/auth/cloud-platform'];
+```
+
+### Python
+
+```python
+import google.auth
+
+# Via ADC (auto-detects external account config from GOOGLE_APPLICATION_CREDENTIALS)
+credentials, project = google.auth.default(
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+Or load from file explicitly:
+
+```python
+import google.auth
+
+credentials, project = google.auth.load_credentials_from_file(
+    '/path/to/config.json',
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+Or direct instantiation by credential type:
+
+```python
+# Identity Pool (OIDC/SAML)
+from google.auth import identity_pool
+
+credentials = identity_pool.Credentials.from_file(
+    '/path/to/config.json',
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# AWS
+from google.auth import aws
+
+credentials = aws.Credentials.from_file(
+    '/path/to/config.json',
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+Requirements for ADC with external identities:
+- Grant `roles/browser` to the service account (or specify `projectId` explicitly)
+- Enable Cloud Resource Manager API on the project
+
+## Configurable Token Lifetime
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+  ... \
+  --service-account-token-lifetime-seconds=3600
+```
+
+- Default: 3600 (1 hour)
+- Min: 600 (10 minutes), Max: 43200 (12 hours)
+- Lifetimes > 1 hour require org policy: `constraints/iam.allowServiceAccountCredentialLifetimeExtension`
+
+## Security Considerations
+
+- **Validate external credential configs** — verify `token_url`, `token_info_url`, `service_account_impersonation_url` point to `googleapis.com`
+- **Restrict executable access** — prevent unauthorized processes from reading credentials from stdout
+- **Make config files read-only** — prevent modification of executable command paths
+- **Prefer file/URL-sourced** over executable-sourced credentials when possible
+- **Implement caching** in custom suppliers — neither the Node.js nor Python library caches external tokens

package/plugins/sheleg-dev/skills/google-signin/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: google-signin
+description: >-
+  Use when implementing, reviewing or debugging Google login / sign-in / sign-up on a website —
+  wiring the GIS button or One Tap, verifying Google ID tokens on the server, linking Google to
+  existing password accounts, or fixing "origin is not allowed for the given client ID". Covers
+  GCP OAuth client setup, backend ID-token verification, three-way account linking with the pre-
+  hijacking guard, login-CSRF defense, nonce/replay protection and a mandatory security
+  checklist. Triggers - "sign in with google", "google login", "google sign-in button", "GIS",
+  "google.accounts.id", "gsi/client", "verify google token", "one tap", "account linking",
+  "login csrf", "g_csrf_token", "вход через Google", "кнопка входа Google", "связать аккаунты",
+  "проверить токен Google". For the broader library surface use google-auth instead.
+---
+
+# Google Sign-In (GIS) — production web login
+
+Condensed operating instructions. Full narrative guide with diagrams, token
+anatomy, troubleshooting table, and a copy-paste FastAPI + JS skeleton:
+[references/full-guide.md](references/full-guide.md) — read it when
+implementing from scratch. A live reference implementation exists in the
+Prowl repo (`0xDEV`): `web/auth.py`, `web/server.py:1657`
+(`/api/auth/google`), `web/static/js/app.js:16-110`.
+
+## Pick the right flow first
+
+- Only need "who is this user?" → **GIS ID-token flow** (this skill): load
+  `https://accounts.google.com/gsi/client`, receive one Google-signed JWT,
+  verify server-side. No redirect URI, no client secret, no Google-token
+  storage.
+- Need to call Google APIs (Gmail/Drive/Calendar) on the user's behalf →
+  OAuth 2.0 **authorization-code** flow instead (redirect URI + client
+  secret + refresh tokens). Never use the code flow just for login.
+
+## Core flow (ID-token)
+
+1. Frontend: `google.accounts.id.initialize({ client_id, callback, nonce })`
+   + `renderButton()`. Generate a **fresh random nonce per render**
+   (`crypto.randomUUID()`). The GSI script loads async — retry rendering
+   (e.g. 20 × 150 ms) instead of silently dropping the button.
+2. Callback receives `{ credential }` — a Google-signed ID token (JWT).
+   POST it with the nonce to your backend. Never treat it as a session.
+3. Backend: verify with the official lib — Python
+   `google.oauth2.id_token.verify_oauth2_token(credential, transport, CLIENT_ID)`,
+   Node `google-auth-library` `verifyIdToken({ idToken, audience })`. That
+   checks signature (Google JWKS), `aud`, `iss`, `exp`. Never hand-decode
+   and trust the payload.
+4. Additionally require `email_verified == true` and token `nonce` claim ==
+   submitted nonce.
+5. Find-or-create the user, then issue YOUR OWN session (app JWT) as an
+   **HttpOnly + Secure + SameSite=Strict cookie**. Google's token is
+   verified once, never stored, never logged.
+
+## Identity & account linking (three-way branch)
+
+Key the user on `sub` (stable Google user ID; store as `google_id`) — never
+on email (emails change, `sub` doesn't). On each Google login:
+
+1. Record with this `google_id` exists → login (refresh name/picture).
+2. Email matches an existing account without `google_id` → link, BUT apply
+   the **pre-hijacking guard**: if that account is password-based and its
+   email was never verified, REFUSE the auto-link ("sign in with your
+   password instead"). Otherwise an attacker who pre-registered the
+   victim's email with a known password captures the victim's first Google
+   login into the attacker's record.
+3. No match → create the user with `email_verified=True`, empty password
+   hash.
+
+## Login-CSRF (cover BOTH delivery flows)
+
+- Form-POST flow (`login_uri` auto-POST): GIS double-submits `g_csrf_token`
+  in body AND cookie — compare constant-time (`hmac.compare_digest`);
+  reject if either side is missing.
+- JS-fetch flow: no `g_csrf_token` — enforce same-origin via Fetch-Metadata
+  (`Sec-Fetch-Site: same-origin`) with an Origin-allowlist fallback.
+
+Without this, an attacker's page can force-POST the *attacker's* credential
+and silently log the victim into the attacker's account.
+
+## Setup (GCP)
+
+1. Cloud Console → APIs & Services → OAuth consent screen (External;
+   publish it — in "Testing" only allowlisted users can sign in).
+2. Credentials → Create OAuth client ID → **Web application** →
+   **Authorized JavaScript origins** = every origin the button renders on,
+   incl. `http://localhost:<port>` for dev (scheme+host+port, no path, no
+   trailing slash). **Authorized redirect URIs: leave empty** for GIS.
+3. Ship only `GOOGLE_CLIENT_ID` (public; env var; one source of truth —
+   inject into HTML server-side, e.g. via a `<meta>` tag). The client
+   secret is UNUSED in the GIS flow — never put it in the app.
+4. CSP if present: allow `https://accounts.google.com` in `script-src`,
+   `connect-src`, `frame-src`.
+5. If `GOOGLE_CLIENT_ID` is empty → hide the button and return
+   "not configured" server-side (honest degradation, no crash).
+
+## Security checklist (verify ALL before calling it done)
+
+- [ ] Signature verified via official lib against Google JWKS (no
+      `verify=False`, no manual base64 decode-and-trust)
+- [ ] `aud` == your client ID; `exp` enforced
+- [ ] `email_verified` required
+- [ ] Nonce: fresh per render, checked server-side against the token claim
+- [ ] Pre-hijacking guard on email-based linking
+- [ ] Login-CSRF: `g_csrf_token` double-submit AND same-origin check for
+      the JS flow
+- [ ] Own session cookie: HttpOnly + Secure + SameSite=Strict
+- [ ] `/api/auth/*` rate-limited; auth events logged WITHOUT the credential
+- [ ] Session revocation path exists (e.g. an `auth_version`/`ver` claim
+      check)
+- [ ] Logout also calls `google.accounts.id.disableAutoSelect()`
+
+## Debugging quick table
+
+| Symptom | Fix |
+|---|---|
+| "The given origin is not allowed for the given client ID" | Add the exact origin (port, `www.`) to Authorized JavaScript origins; propagation takes minutes |
+| Button never renders | GSI async race (add retry loop), empty client ID, or CSP blocks `accounts.google.com` |
+| "Token used too early/expired" | Server clock skew → sync NTP |
+| Audience mismatch | Frontend/backend client IDs differ → single env source of truth |
+| `access_denied` on consent | Consent screen still in Testing → publish the app |
+| Works locally, breaks in prod | Prod origin missing in GCP, or `Secure` cookie served over plain HTTP |
+| One Tap missing / FedCM console warnings | FedCM is mandatory since Aug 2025 and the opt-out is gone (checked 2026-08-06). Load `gsi/client` from Google and keep it current — a vendored or pinned copy is the real break. The rendered button flow is unaffected; code branching on the old `isNotDisplayed()` moment callbacks is not |