@anura-gate/watcher-jira 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,197 @@
+# GATE Watcher — Jira
+
+Self-hosted daemon that monitors your Jira Cloud projects for issue updates, comments, and transitions, pushing them to GATE for security processing. **Your Jira credentials never leave your machine.**
+
+## How it works
+
+```
+Your Machine (Watcher)              GATE Cloud
+┌─────────────────────┐        ┌──────────────────┐
+│ Jira API polling     │───────>│ Security pipeline │
+│ (creds stay HERE)    │<───────│ (redact, policy,  │
+│                      │ poll   │  audit, forward)  │
+└─────────────────────┘        └──────────────────┘
+```
+
+## Quick Start (CLI)
+
+```bash
+cd gate-watcher-jira
+npm install
+
+# Create .env (or pass env vars directly)
+cp .env.example .env
+# Fill in GATE_KEY, GATE_INTEGRATION_ID, and Jira credentials
+
+npm start
+```
+
+On first run with OAuth, the browser opens automatically — click **Allow**, and you're connected.
+
+## Auth Modes
+
+### OAuth 2.0 (recommended)
+
+Browser-based authorization. No manual tokens or emails needed.
+
+1. Register an app at [developer.atlassian.com/console/myapps](https://developer.atlassian.com/console/myapps)
+2. Set callback URL to `http://localhost:*/callback`
+3. Enable scopes: `read:jira-work`, `write:jira-work`, `read:jira-user`, `offline_access`
+4. Set `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET` in `.env`
+5. Run the watcher — browser opens, click Allow, done
+
+Tokens are stored in `~/.gate/jira-oauth.json` and auto-refresh. Use `--auth` to re-authorize or `--logout` to clear stored tokens.
+
+### API Token (headless / CI)
+
+For environments without a browser.
+
+1. Create an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Set `JIRA_DOMAIN`, `JIRA_EMAIL`, and `JIRA_TOKEN` in `.env`
+
+## Embed in Your App (SDK)
+
+```bash
+npm install @anura-gate/watcher-jira
+```
+
+### With OAuth
+
+```js
+const { GateJiraWatcher } = require("@anura-gate/watcher-jira");
+
+const watcher = new GateJiraWatcher({
+  gateKey: "gk-xxx",
+  integrationId: "int_xxx",
+  oauth: {
+    accessToken: "eyJ...",
+    cloudId: "abcd-1234-...",
+    siteUrl: "https://yourcompany.atlassian.net",
+  },
+  projects: ["PROJ", "ENG"], // optional — omit to watch all projects
+});
+
+await watcher.start();
+```
+
+### With API Token
+
+```js
+const watcher = new GateJiraWatcher({
+  gateKey: "gk-xxx",
+  integrationId: "int_xxx",
+  jiraDomain: "yourcompany.atlassian.net",
+  jiraEmail: "you@company.com",
+  jiraToken: "ATATT3x...",
+  projects: ["PROJ", "ENG"],
+});
+
+await watcher.start();
+```
+
+### Listening to Events
+
+```js
+watcher.on("ready", (displayName) => {
+  console.log(`Jira connected: ${displayName}`);
+});
+
+watcher.on("event", (event, result) => {
+  console.log(`Event: ${event.eventType}, Issue: ${event.content.metadata.issueKey}`);
+  console.log(`Security actions: ${result.securityActions}`);
+});
+
+watcher.on("action_result", ({ action, success, error }) => {
+  console.log(`${action}: ${success ? "done" : error}`);
+});
+
+// Later...
+await watcher.stop();
+```
+
+## Detected Events
+
+| Event Type | Trigger |
+|---|---|
+| `issue_transitioned` | Status changed (e.g. To Do → In Progress) |
+| `issue_assigned` | Assignee changed |
+| `issue_resolved` | Resolution set (Done, Won't Fix, etc.) |
+| `comment_added` | New comment on an issue |
+| `priority_changed` | Priority changed |
+| `labels_changed` | Labels added or removed |
+| `sprint_changed` | Issue moved to a different sprint |
+| `issue_updated` | Summary, description, or other field changed |
+
+## Outbound Actions
+
+GATE can queue actions for the watcher to execute locally:
+
+| Action | Required Params | Optional Params |
+|---|---|---|
+| `create_issue` | `project`, `summary` | `description`, `issueType`, `assignee`, `priority`, `labels` |
+| `add_comment` | `issueKey`, `body` | — |
+| `transition_issue` | `issueKey`, `transition` | — |
+| `assign_issue` | `issueKey` | `accountId` (null = unassign) |
+| `update_issue` | `issueKey` | `summary`, `description`, `priority`, `labels` |
+
+## SDK Events
+
+| Event | Args | Description |
+|---|---|---|
+| `ready` | `(displayName)` | Connected to Jira |
+| `event` | `(event, result)` | Jira event processed by GATE |
+| `action` | `(action)` | Outbound action received from GATE queue |
+| `action_result` | `({ actionId, action, success, result, error })` | Outbound action completed |
+| `gate_error` | `({ path, status, error })` | GATE API call failed |
+| `jira_error` | `({ path, error })` | Jira API call failed |
+| `limit_reached` | `(type)` | Plan limit hit |
+| `stopped` | — | Watcher fully shut down |
+
+## SDK Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `gateKey` | Yes | — | Virtual key (`gk-xxx`) |
+| `integrationId` | Yes | — | Integration ID (`int_xxx`) |
+| `oauth` | * | — | OAuth credentials (`{ accessToken, cloudId, siteUrl }`) |
+| `jiraDomain` | * | — | Jira Cloud domain (`yourcompany.atlassian.net`) |
+| `jiraEmail` | * | — | Atlassian account email |
+| `jiraToken` | * | — | Jira API token |
+| `gateUrl` | No | `"https://anuragate.com"` | GATE cloud URL |
+| `projects` | No | `[]` | Project keys to watch. Empty = all |
+| `pollInterval` | No | `30000` | ms between Jira API polls |
+| `heartbeatInterval` | No | `30000` | ms between heartbeats |
+| `sessionId` | No | — | Session ID for multi-tenant use |
+| `sessionLabel` | No | — | Human-readable session label |
+| `sessionMetadata` | No | `{}` | Arbitrary metadata for the session |
+
+\* Either `oauth` or all three of `jiraDomain` + `jiraEmail` + `jiraToken` are required.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GATE_KEY` | Yes | Your GATE virtual key |
+| `GATE_INTEGRATION_ID` | Yes | Integration ID from the dashboard |
+| `JIRA_CLIENT_ID` | OAuth | Atlassian OAuth app client ID |
+| `JIRA_CLIENT_SECRET` | OAuth | Atlassian OAuth app client secret |
+| `JIRA_DOMAIN` | API Token | Jira Cloud domain (`yourcompany.atlassian.net`) |
+| `JIRA_EMAIL` | API Token | Atlassian account email |
+| `JIRA_TOKEN` | API Token | Jira API token |
+| `JIRA_PROJECTS` | No | Comma-separated project keys: `PROJ,ENG` |
+| `GATE_URL` | No | Custom GATE cloud URL |
+| `WEB_PORT` | No | Port for the dev dashboard (CLI only) |
+
+## CLI Flags
+
+| Flag | Description |
+|---|---|
+| `--auth` | Force re-authorization (discard stored OAuth tokens) |
+| `--logout` | Clear stored OAuth tokens and exit |
+
+## Security Model
+
+- Jira credentials stored locally on YOUR machine (`.env` or `~/.gate/jira-oauth.json`)
+- GATE cloud never sees or stores your Jira credentials
+- All event content passes through GATE's security pipeline (redaction, policies, audit)
+- Billing, limits, and security enforced server-side

package/lib/oauth.js

@@ -53,7 +53,7 @@ const TOKEN_FILE = path.join(TOKEN_DIR, "jira-oauth.json");
  * @param {number} [opts.port]        — Local callback port (0 = random)
  * @returns {Promise<OAuthResult>}
  */
-async function authorize({ clientId, clientSecret, port = 0 }) {
+async function authorize({ clientId, clientSecret, port = 9876 }) {
   const state = crypto.randomBytes(16).toString("hex");
 
   // Start local server to receive the callback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anura-gate/watcher-jira",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "GATE Watcher — Self-hosted Jira event monitor with OAuth 2.0. Credentials never leave your machine.",
   "main": "index.js",
   "bin": {