crewly 1.5.22 → 1.6.0

package/config/skills/orchestrator/credential-manager/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: Credential Manager
+description: "Manage workspace credentials (Google OAuth accounts, service API keys) that skills use to call third-party services on the user's behalf. Primary flow for remote users over Slack: start-google-oauth returns a link the user clicks on their device; they sign in and paste the resulting JSON back, then complete-google-oauth saves the credential. Supports multi-account."
+version: 1.1.0
+category: management
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - add gmail account
+  - add google account
+  - add api key
+  - list credentials
+  - show credentials
+  - what credentials
+  - delete credential
+  - revoke credential
+  - connect google
+  - connect gmail
+  - read gmail
+  - check unread emails
+  - unread messages
+  - my inbox
+tags:
+  - credentials
+  - oauth
+  - gmail
+  - google
+  - api-key
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Credential Manager
+
+Manages the workspace's credential store used by skills. Supports Google OAuth
+(multi-account) and API keys.
+
+**Credential values are never returned** — only metadata (id, name, email,
+scopes). The actual tokens stay encrypted on disk and are only exposed to
+skills at execution time via per-slot env vars.
+
+## Primary flow: Remote user via Slack
+
+The user is on Slack and cannot run terminal commands. Use this flow:
+
+### 1. Start — return a sign-in link
+
+```bash
+bash execute.sh '{"action":"start-google-oauth"}'
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=...",
+  "instructions": "Send authUrl to the user. They click it..."
+}
+```
+
+**Send the `authUrl` to the user**. Tell them:
+> Please click this link, sign in with the Google account you want to add,
+> then copy the entire JSON block shown on the success page and paste it back here.
+
+The URL opens on their device (phone, laptop, whatever). Google shows the
+consent screen ("Google Workspace Extension for Gemini CLI wants to access...").
+After they approve, they land on a page titled **"Success! Credentials Ready"**
+with a JSON block like:
+
+```json
+{
+  "refresh_token": "1//...",
+  "scope": "...",
+  "token_type": "Bearer",
+  "access_token": "ya29...",
+  "expiry_date": 1234567890123
+}
+```
+
+### 2. Complete — save the credential
+
+After the user pastes the JSON back, call:
+
+```bash
+bash execute.sh '{
+  "action":"complete-google-oauth",
+  "name":"info-steam-fun",
+  "credentialsJson": {"refresh_token":"...","access_token":"...","scope":"...","token_type":"Bearer","expiry_date":...}
+}'
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "credential": {
+    "id": "cred-abc123...",
+    "name": "info-steam-fun",
+    "type": "google-oauth",
+    "provider": "google",
+    "helper": "gemini-cli-workspace",
+    "accountEmail": "info@steam-fun.com",
+    "scopes": [...]
+  }
+}
+```
+
+### 3. Repeat for more accounts
+
+Just call `start-google-oauth` → send new URL → `complete-google-oauth` again
+with a different name. No extension state to clear (headless mode never
+touches it).
+
+---
+
+## Developer flow (on-box only)
+
+If you're running on the same machine as Crewly AND have the Gemini CLI
+Workspace extension set up for interactive login, these still work:
+
+### `import-google`
+
+Import the extension's currently-active login:
+
+```bash
+bash execute.sh '{"action":"import-google","name":"info-steam-fun"}'
+```
+
+Precondition: user has run `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true gemini`
+and completed sign-in, leaving tokens in the extension's file cache.
+
+### `clear-gemini-cli`
+
+Delete the extension's cached token file so the next local login captures
+a fresh account:
+
+```bash
+bash execute.sh '{"action":"clear-gemini-cli"}'
+```
+
+---
+
+## Other actions
+
+### `list`
+
+List credentials (filter optional).
+
+```bash
+bash execute.sh '{"action":"list"}'
+bash execute.sh '{"action":"list","type":"google-oauth"}'
+bash execute.sh '{"action":"list","provider":"gemini"}'
+```
+
+### `add-api-key`
+
+```bash
+bash execute.sh '{"action":"add-api-key","name":"gemini-main","provider":"gemini","value":"AIza..."}'
+```
+
+### `delete`
+
+```bash
+bash execute.sh '{"action":"delete","id":"cred-abc123..."}'
+```
+
+### `read-gmail`
+
+Read unread emails from the named Google account:
+
+```bash
+bash execute.sh '{"action":"read-gmail","name":"info-steam-fun"}'
+bash execute.sh '{"action":"read-gmail","name":"personal-gmail","maxResults":5}'
+```
+
+---
+
+## Multi-account example (remote Slack user)
+
+```
+User: "Add info@steam-fun.com to Crewly"
+Orchestrator:
+  1. bash execute.sh '{"action":"start-google-oauth"}'
+  2. Gets authUrl back.
+  3. Replies in Slack:
+     "Click this to sign in with info@steam-fun.com: <authUrl>
+      After signing in, copy the JSON block from the 'Success!' page
+      and paste it back here."
+
+User: (clicks on phone, signs in, pastes JSON)
+  {"refresh_token":"...","access_token":"...","scope":"...","token_type":"Bearer","expiry_date":...}
+
+Orchestrator:
+  1. bash execute.sh '{"action":"complete-google-oauth","name":"info-steam-fun","credentialsJson":<pasted JSON>}'
+  2. Replies: "✓ Added info-steam-fun (info@steam-fun.com)."
+
+User: "Now add my personal gmail"
+Orchestrator:
+  repeats start → URL → user pastes → complete, with name=personal-gmail.
+
+User: "What's unread in info's inbox?"
+Orchestrator:
+  bash execute.sh '{"action":"read-gmail","name":"info-steam-fun"}'
+  → returns summary of unread emails.
+```
+
+## Errors
+
+- `name is required` / `credentialsJson is required` — missing fields in complete action
+- `credentialsJson is not valid JSON` — user pasted something other than the JSON block
+- `credentialsJson is missing access_token or refresh_token` — user pasted a partial JSON
+- `No google-oauth credential found with name '...'` — `read-gmail` lookup failed; try `list`
+- `Credential '...' is revoked` — the refresh token was revoked by the user or Google; re-run the OAuth flow

package/config/skills/orchestrator/credential-manager/execute.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+# Credential Manager — wraps /api/credentials REST endpoints so the
+# orchestrator can manage Google OAuth accounts and API keys on user request.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT=$(read_json_input "${1:-}")
+if [ -z "$INPUT" ]; then
+  error_exit "Usage: execute.sh '{\"action\":\"list|import-google|clear-gemini-cli|add-api-key|delete|read-gmail\", ...}'"
+fi
+
+ACTION=$(printf '%s' "$INPUT" | jq -r '.action // empty')
+require_param "action" "$ACTION"
+
+case "$ACTION" in
+  list)
+    TYPE=$(printf '%s' "$INPUT" | jq -r '.type // empty')
+    PROVIDER=$(printf '%s' "$INPUT" | jq -r '.provider // empty')
+    RESP=$(api_call GET "/credentials")
+    # Filter client-side
+    printf '%s' "$RESP" | jq --arg type "$TYPE" --arg provider "$PROVIDER" '
+      .data
+      | map(select($type == "" or .type == $type))
+      | map(select($provider == "" or .provider == $provider))
+      | map({id, name, type, provider, helper, accountEmail, scopes, status, createdAt, lastUsedAt})
+    '
+    ;;
+
+  import-google)
+    # Import from gemini-cli extension's LOCAL file (developer / on-box user).
+    # For remote users over Slack, use start-google-oauth + complete-google-oauth instead.
+    NAME=$(printf '%s' "$INPUT" | jq -r '.name // empty')
+    require_param "name" "$NAME"
+    BODY=$(jq -nc --arg name "$NAME" '{name: $name}')
+    RESP=$(api_call POST "/credentials/oauth/import-gemini-cli" "$BODY")
+    printf '%s' "$RESP" | jq '
+      if .success == true then
+        {success: true, credential: .data | {id, name, type, provider, helper, accountEmail, scopes}}
+      else
+        {success: false, error: .error}
+      end
+    '
+    ;;
+
+  start-google-oauth)
+    # Headless flow — returns a URL for a remote user to click.
+    # Optionally takes scopes override; defaults to broad Workspace set.
+    SCOPES_ARG=$(printf '%s' "$INPUT" | jq -c '.scopes // empty')
+    if [ -n "$SCOPES_ARG" ]; then
+      BODY=$(printf '%s' "$SCOPES_ARG" | jq -c '{scopes: .}')
+    else
+      BODY='{}'
+    fi
+    RESP=$(api_call POST "/credentials/oauth/google/start" "$BODY")
+    printf '%s' "$RESP" | jq '
+      if .success == true then
+        {
+          success: true,
+          authUrl: .data.authUrl,
+          instructions: "Send authUrl to the user. They click it on their device, sign in with the Google account they want to add, and copy the JSON shown on the success page. Then call action=complete-google-oauth with the pasted JSON."
+        }
+      else
+        {success: false, error: .error}
+      end
+    '
+    ;;
+
+  complete-google-oauth)
+    # Accept the JSON the user pasted from the success page. Save as a new credential.
+    NAME=$(printf '%s' "$INPUT" | jq -r '.name // empty')
+    require_param "name" "$NAME"
+    # Accept either the raw JSON string or a parsed object under .credentialsJson
+    CREDS=$(printf '%s' "$INPUT" | jq -c '.credentialsJson // empty')
+    if [ -z "$CREDS" ] || [ "$CREDS" = "null" ]; then
+      error_exit "credentialsJson is required (paste the JSON block from the OAuth success page)"
+    fi
+    BODY=$(jq -nc --arg name "$NAME" --argjson creds "$CREDS" '{name: $name, credentialsJson: $creds}')
+    RESP=$(api_call POST "/credentials/oauth/google/complete" "$BODY")
+    printf '%s' "$RESP" | jq '
+      if .success == true then
+        {success: true, credential: .data | {id, name, type, provider, helper, accountEmail, scopes, status}}
+      else
+        {success: false, error: .error}
+      end
+    '
+    ;;
+
+  clear-gemini-cli)
+    api_call POST "/credentials/oauth/gemini-cli/clear-extension-file" "" \
+      | jq '{cleared: (.success == true), error: .error}'
+    ;;
+
+  add-api-key)
+    NAME=$(printf '%s' "$INPUT" | jq -r '.name // empty')
+    PROVIDER=$(printf '%s' "$INPUT" | jq -r '.provider // empty')
+    VALUE=$(printf '%s' "$INPUT" | jq -r '.value // empty')
+    require_param "name" "$NAME"
+    require_param "provider" "$PROVIDER"
+    require_param "value" "$VALUE"
+    BODY=$(jq -nc --arg name "$NAME" --arg provider "$PROVIDER" --arg value "$VALUE" \
+      '{name: $name, provider: $provider, value: $value}')
+    RESP=$(api_call POST "/credentials/api-key" "$BODY")
+    printf '%s' "$RESP" | jq '
+      if .success == true then
+        {success: true, credential: .data | {id, name, type, provider, createdAt}}
+      else
+        {success: false, error: .error}
+      end
+    '
+    ;;
+
+  delete)
+    ID=$(printf '%s' "$INPUT" | jq -r '.id // empty')
+    require_param "id" "$ID"
+    api_call DELETE "/credentials/${ID}" | jq '{deleted: (.success == true), error: .error}'
+    ;;
+
+  read-gmail)
+    NAME=$(printf '%s' "$INPUT" | jq -r '.name // empty')
+    MAX=$(printf '%s' "$INPUT" | jq -r '.maxResults // 10')
+    require_param "name" "$NAME"
+
+    # 1. Find the credential by name
+    LIST_RESP=$(api_call GET "/credentials")
+    CRED_ID=$(printf '%s' "$LIST_RESP" | jq -r --arg name "$NAME" '
+      .data[]? | select(.name == $name and .type == "google-oauth") | .id
+    ' | head -n 1)
+
+    if [ -z "$CRED_ID" ]; then
+      AVAILABLE=$(printf '%s' "$LIST_RESP" | jq -r '
+        .data[]? | select(.type == "google-oauth") | .name
+      ' | paste -sd ", " -)
+      error_exit "No google-oauth credential named '$NAME'. Available Google accounts: ${AVAILABLE:-none}. Use action=list to confirm."
+    fi
+
+    # 2. Execute gmail-reader skill with the credential bound to 'gmail' slot
+    EXEC_BODY=$(jq -nc --arg cid "$CRED_ID" --arg max "$MAX" '{
+      agentId: "orchestrator",
+      roleId: "orchestrator",
+      userInput: $max,
+      credentialBindings: {gmail: $cid}
+    }')
+    RESP=$(api_call POST "/skills/skill-gmail-reader/execute" "$EXEC_BODY")
+    # Extract the stdout from the skill execution so the orchestrator sees
+    # the human-readable summary directly
+    printf '%s' "$RESP" | jq '
+      if .success == true then
+        {
+          credential: "'"$NAME"'",
+          credentialId: "'"$CRED_ID"'",
+          success: .data.success,
+          output: .data.output,
+          error: .data.error,
+          durationMs: .data.durationMs
+        }
+      else
+        {success: false, error: .error}
+      end
+    '
+    ;;
+
+  *)
+    error_exit "Unknown action: '$ACTION'. Valid: list, start-google-oauth, complete-google-oauth, import-google, clear-gemini-cli, add-api-key, delete, read-gmail"
+    ;;
+esac

package/dist/backend/backend/src/controllers/credentials/credentials.controller.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Credentials REST Controller
+ *
+ * Exposes workspace credential management over REST so the frontend (and
+ * Cloud portal) can list, add, rename, delete, and OAuth-import credentials.
+ *
+ * All endpoints return `{ success, data?, error? }` matching the rest of
+ * the Crewly API surface. Secret values (token payloads, API keys) are
+ * never returned — only registry metadata.
+ *
+ * @module controllers/credentials/credentials.controller
+ */
+import type { Request, Response, NextFunction } from 'express';
+/** Reset the helper singleton — for tests only. */
+export declare function _resetGeminiHelperForTesting(): void;
+/**
+ * GET /api/credentials — list all credential metadata (never values).
+ */
+export declare function listCredentials(_req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * GET /api/credentials/:id — metadata for a single credential.
+ */
+export declare function getCredentialById(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * POST /api/credentials/api-key — add an API key credential.
+ * Body: { name, provider, value }
+ */
+export declare function addApiKey(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * PATCH /api/credentials/:id — update metadata (name, status).
+ * Body: { name?, status? }
+ */
+export declare function updateCredentialHandler(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * DELETE /api/credentials/:id — delete credential (registry entry + .enc file).
+ */
+export declare function deleteCredentialHandler(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * POST /api/credentials/oauth/import-gemini-cli — capture current extension
+ * login into a new credential.
+ * Body: { name }
+ *
+ * Precondition: the user has run
+ *   `GEMINI_CLI_WORKSPACE_FORCE_FILE_STORAGE=true gemini`
+ * and signed in via the workspace extension.
+ */
+export declare function importOAuthFromGeminiCli(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * POST /api/credentials/oauth/gemini-cli/clear-extension-file —
+ * delete the extension's cached token file so the next extension login
+ * captures a different account.
+ */
+export declare function clearGeminiCliExtensionFile(_req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * POST /api/credentials/oauth/google/start
+ *
+ * Build a Google OAuth URL that the caller can send to a remote user (via
+ * Slack, email, etc.). The URL opens on the user's device, they sign in,
+ * and the gemini-cli cloud function returns a page showing the credentials
+ * JSON for the user to copy back.
+ *
+ * Body: { scopes?: string[] }    (optional override)
+ * Returns: { success, data: { authUrl } }
+ */
+export declare function startGoogleOAuth(req: Request, res: Response, _next: NextFunction): Promise<void>;
+/**
+ * POST /api/credentials/oauth/google/complete
+ *
+ * Accept the credentials JSON that the user copied from the OAuth success
+ * page, verify it, fetch the account email, and save as a new Crewly
+ * credential.
+ *
+ * Body: {
+ *   name: string,
+ *   credentialsJson: string | object    (the JSON blob the user pasted)
+ * }
+ * Returns: { success, data: CredentialRegistryEntry }
+ */
+export declare function completeGoogleOAuth(req: Request, res: Response, _next: NextFunction): Promise<void>;
+//# sourceMappingURL=credentials.controller.d.ts.map

package/dist/backend/backend/src/controllers/credentials/credentials.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.controller.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/controllers/credentials/credentials.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA6B/D,mDAAmD;AACnD,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAMD;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAQf;AAoCD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAmGf"}