gcal-oauth-bridge

Interact with the Calendar Bridge — a self-hosted Node.js service that provides a persistent REST API for Google Calendar events. Handles OAuth token auto-re...

Security Scan

The skill's requests and instructions are coherent with its stated purpose: it needs Google OAuth client credentials to perform an initial OAuth setup for a locally hosted Calendar Bridge service and otherwise operates via localhost API calls.

Purpose & Capability

The skill is a bridge for Google Calendar and legitimately requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for the OAuth setup; CALENDAR_BRIDGE_API_KEY as an optional API protection header is also appropriate.

Instruction Scope

SKILL.md stays on-topic: it instructs cloning the GitHub repo, running the Node service, performing the OAuth browser flow, and calling local endpoints. It does not ask the agent to read unrelated system files or to exfiltrate data to external endpoints. It does recommend SSH port forwarding for remote servers and using systemd to keep the service running (both reasonable for this purpose).

Install Mechanism

This is an instruction-only skill (no install spec), so nothing is automatically downloaded/installed by the platform. The instructions ask the user to git clone and run npm install on the upstream GitHub repo — a normal but potentially risky manual action (running third-party Node code).

Credentials

Requested env vars (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) are directly required for OAuth setup; the optional CALENDAR_BRIDGE_API_KEY is sensible for protecting the local API. There are no unrelated or excessive secret requests.

Persistence & Privilege

The skill does not request special platform privileges (always is false). It recommends running the service as a user systemd unit to keep it persistent, which is reasonable for a local service but does create persistent presence on the host if you follow the instructions.

Assessment

This skill appears to do what it says, but take these precautions before installing: 1) Verify the GitHub repository and author (https://github.com/DanielKillenberger/gcal-oauth-bridge) and review app.js yourself before running npm install/node. 2) Treat GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET as sensitive: do not paste them into chat; store them on the host where the bridge runs. 3) Protect tokens.json and, if used, set a strong CALENDAR_BRIDGE_API_KEY to avoid unauthenticated local access. 4) If deploying on a remote VPS, use SSH tunnel as instructed (or secure the service behind a firewall) so the OAuth redirect is safe. 5) Understand that following the SKILL.md will create a persistent service (systemd user unit) on your machine — only proceed on a host you control. 6) If you want to avoid running third-party code, consider using an officially supported Google Calendar integration instead.

Calendar Bridge Skill

Use this skill to interact with the Calendar Bridge service — a local REST API that wraps Google Calendar OAuth with persistent token storage and auto-refresh.

GitHub: https://github.com/DanielKillenberger/gcal-oauth-bridge

What is Calendar Bridge?

A tiny Node.js/Express service running at http://localhost:3000 that:

• Handles Google Calendar OAuth once via browser
• Stores and auto-refreshes tokens (solves the "token expired every 7 days" problem)
• Exposes a dead-simple REST API for events, calendars, and auth

API Endpoints

Endpoint	Description
GET /health	Service status + auth state
GET /auth/url	Get OAuth consent URL
GET /events?days=7	Upcoming events from primary calendar
GET /events?days=7&calendar=all	Events from ALL calendars
GET /events?days=7&calendar=<id>	Events from a specific calendar
GET /calendars	List all available calendars
POST /auth/refresh	Force token refresh (normally automatic)

Events response includes: id, summary, start, end, location, description, htmlLink, status, calendarId, calendarSummary

Checking Events

# Quick event check (7 days, primary calendar)
curl http://localhost:3000/events

# All calendars, next 14 days
curl http://localhost:3000/events?days=14&calendar=all

# With API key (if CALENDAR_BRIDGE_API_KEY is configured)
curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/events?calendar=all

To call from OpenClaw/skill context (no API key needed when running on same host):

GET http://localhost:3000/events?calendar=all&days=7

First-Time Setup

1. Clone and install

git clone https://github.com/DanielKillenberger/gcal-oauth-bridge.git
cd gcal-oauth-bridge
npm install
cp .env.example .env
# Edit .env with GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

2. Get Google OAuth credentials

• Go to https://console.cloud.google.com/apis/credentials
• Create OAuth 2.0 Client ID (Desktop app)
• Enable Google Calendar API
• Add redirect URI: http://localhost:3000/auth/callback
• Copy Client ID + Secret to .env

3. Start the service

node app.js
# or: npm start

4. Authorize (one-time browser flow)

If on a remote VPS, first tunnel port 3000:

# From your local machine:
ssh -L 3000:localhost:3000 your-server

Then:

curl http://localhost:3000/auth/url
# Open the returned URL in your browser
# Complete Google consent → tokens saved automatically

Verify:

curl http://localhost:3000/health
# {"status":"ok","authenticated":true,"needsRefresh":false}

5. Keep it running (systemd)

systemctl --user enable calendar-bridge.service
systemctl --user start calendar-bridge.service

Re-authentication

If tokens are ever revoked (rare — auto-refresh prevents expiry):

1. ssh -L 3000:localhost:3000 your-server
2. curl http://localhost:3000/auth/url → open URL → complete consent
3. Done — new tokens overwrite old ones

Troubleshooting

• {"error":"Not authenticated"} → Run the OAuth setup flow above
• 401 Unauthorized → CALENDAR_BRIDGE_API_KEY is set; add Authorization: Bearer <key> header
• Can't reach localhost:3000 → Service not running; check systemctl --user status calendar-bridge
• "invalid_grant" / "token expired" → Tokens were revoked externally; re-authenticate

Personal Gmail Users

Works with personal Gmail. Google shows an "unverified app" warning — click Advanced → Go to [app] to proceed. Tokens are stored locally on your server, not shared with anyone.

Files

• GitHub repo: https://github.com/DanielKillenberger/gcal-oauth-bridge
• App: app.js — main Express server
• Config: .env (from .env.example)
• Tokens: tokens.json (auto-generated, gitignored, never committed)