Every request from the CLI to the proxy includes a JWT signed with a shared secret using HMAC-SHA256.

HEADER.PAYLOAD.SIGNATURE

Header:  {"alg": "HS256", "typ": "JWT"}
Payload: {"iat": 1707550000, "exp": 1707550300, "jti": "550e8400-e29b-41d4-a716-446655440000"}

1. Split token into 3 parts (header, payload, signature)
2. Decode and validate header (alg must be HS256)
3. Compute HMAC-SHA256 of header.payload using the shared secret
4. Constant-time compare computed signature with provided signature
5. Decode payload and check exp (with 30s clock skew tolerance)
6. Check iat is not in the future (with 30s tolerance)
7. Check JTI against CacheService for replay detection (5-minute TTL)

• Minimum length: 32 bytes (256 bits) recommended
• Generation: Cryptographic random (e.g., openssl rand -base64 48)
• Storage (CLI): ~/.gproxy/config.json with file permissions 0600
• Storage (Proxy): Apps Script Script Properties (not in source code)
• Rotation: Change the secret in both Script Properties and CLI config; old tokens expire within 5 minutes

Both the CLI (Node.js) and proxy (Apps Script) implement base64url encoding/decoding per RFC 7515:

• Replace + with -
• Replace / with _
• Strip trailing = padding

The CLI uses Buffer.toString('base64') with regex replacement. The proxy uses Utilities.base64Encode() with the same replacement pattern. Both implementations produce identical output for the same input, ensuring interoperability.

Signature verification uses constant-time string comparison to prevent timing attacks:

function constantTimeCompare(a, b) {
  if (typeof a !== 'string' || typeof b !== 'string') return false;
  if (a.length !== b.length) return false;
  var result = 0;
  for (var i = 0; i < a.length; i++) {
    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return result === 0;
}

Note: The length check leaks whether strings are the same length. For HMAC signatures of a fixed algorithm, all outputs have the same length, so this is not a concern.

Apps Script doPost(e) does not expose the client's real IP address. The IP used for allowlisting is client-reported via the clientIp field in the request body. A motivated attacker with the shared secret could spoof any IP.

This is defense-in-depth only — it prevents casual misuse but does not constitute a security boundary.

Set IP_ALLOWLIST in Script Properties as a comma-separated list:

192.168.1.100,10.0.0.0/8,203.0.113.42

Supports:

• Exact IPv4 match: 192.168.1.100
• CIDR notation: 10.0.0.0/8

When enabled, the proxy queries AbuseIPDB's threat intelligence API before processing requests:

The check fails open — if AbuseIPDB is unreachable, the request proceeds. This prioritizes availability over security for this defense-in-depth layer.

The CLI validates that the proxy URL starts with https://. HTTP URLs are rejected with an error. This ensures all traffic between the CLI and Apps Script is encrypted in transit.

The proxy logger (Logger.gs) never records request parameters. Log entries include only:

Email bodies, document content, file data, and other sensitive parameters are never written to the log sheet.

The proxy runs as a Web App deployed as the deploying user with access set to Anyone. This means:

• All Google API calls execute with the permissions of the user who deployed the script
• The "Anyone" access setting means the web app URL is publicly reachable (JWT auth is the access control)
• OAuth scopes are granted at deployment time and apply to all requests

1. Use a strong, randomly generated shared secret (32+ bytes)
2. Restrict Script Properties access to trusted editors only
3. Enable IP allowlisting as an additional layer
4. Monitor the log sheet for unusual activity
5. Rotate the secret periodically and immediately if compromise is suspected
6. Use a dedicated Google account for the proxy if managing sensitive data