@elnora-ai/linear 1.0.1 → 2.0.0

package/templates/SEC-INC-incident.md

@@ -0,0 +1,76 @@
+# SEC-INC: Security Incident Response
+
+## Quick Reference
+- **SLA:** 15min-72hrs (severity-based)
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Security Incidents
+
+## Required Labels
+- `Type: bug`
+- `Layer: devops` or `Layer: backend`
+- `Flag: security`
+- `Flag: compliance`
+- Severity label (see classification)
+
+## Severity Classification
+| Severity | Response Time | Post-Review | Examples |
+|----------|---------------|-------------|----------|
+| Sev 0 (Critical) | 15 minutes | 3 days | Data breach, full outage, active attack |
+| Sev 1 (High) | 1 hour | 5 days | Partial outage, unauthorized access attempt |
+| Sev 2 (Medium) | 4 hours | 10 days | Failed control, suspicious activity |
+| Sev 3 (Low) | 24 hours | 20 days | Policy violation, near-miss |
+
+## Issue Template
+```markdown
+## Security Incident Report
+
+**Incident ID:** SEC-YYYY-XXX
+**Date/Time Discovered:** [YYYY-MM-DD HH:MM UTC]
+**Date/Time Reported:** [YYYY-MM-DD HH:MM UTC]
+**Severity:** [Sev 0 / Sev 1 / Sev 2 / Sev 3]
+
+## Classification
+- **Incident Type:** [Denial of Service / Unauthorized Access / Malicious Code / Data Breach / Policy Violation / Other]
+- **Affected Systems:** [List systems/services affected]
+- **Data Involved:** [Yes/No - if Yes, describe data types]
+- **Customer Impact:** [Yes/No - if Yes, describe impact]
+
+## Initial Assessment
+[Brief description of what happened and initial impact assessment]
+
+## Detection Method
+- [ ] Automated monitoring/alerting
+- [ ] User report
+- [ ] Security scan
+- [ ] Third-party notification
+- [ ] Other: ___
+
+## Containment Actions Taken
+- [ ] Isolated affected systems
+- [ ] Preserved evidence (logs, screenshots)
+- [ ] Reset compromised credentials
+- [ ] Other: ___
+
+## Timeline of Events
+| Time | Event |
+|------|-------|
+| | |
+
+## Escalation
+- [ ] CTO notified (required for Sev 0/1)
+- [ ] Legal notified (if data involved)
+- [ ] Customer notification required? [Yes/No]
+
+## Next Steps
+1. [Action item]
+2. [Action item]
+
+## Resources
+- Incident Response Process: `/security-compliance/incident-management/incident-response-process.md`
+- RCA Template: Create linked RCA-DOC issue if Sev 0/1/2
+```
+
+## Escalation Rules
+- Sev 0/1: Immediate notification to CTO
+- Customer data involved: Notify Legal/CEO
+- Breach determination: CEO + Legal review required

package/templates/SEC-PEN-pentest.md

@@ -0,0 +1,58 @@
+# SEC-PEN: Penetration Test Remediation
+
+## Quick Reference
+- **SLA:** 30-90 days (severity-based)
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Pentest Remediation
+
+## Required Labels
+- `Type: bug`
+- `Flag: security`
+- `Source: Penetration Test`
+- Severity label based on finding risk rating
+
+## Issue Template
+```markdown
+## Penetration Test Finding Remediation
+
+**Finding ID:** [From pentest report, e.g., PT-2025-001]
+**Test Date:** [YYYY-MM-DD]
+**Testing Firm:** [e.g., Workstreet]
+**Report Section:** [Reference to report section]
+
+## Finding Details
+- **Title:** [Finding title from report]
+- **Severity:** [Critical / High / Medium / Low]
+- **CVSS Score:** [X.X] (if provided)
+- **Category:** [OWASP Top 10 category if applicable]
+
+## Description
+[Copy finding description from pentest report]
+
+## Affected Component
+- **URL/Endpoint:** [Affected URL or API endpoint]
+- **System:** [Frontend / Backend / Infrastructure]
+
+## Proof of Concept
+[Summary of how tester exploited the vulnerability]
+
+## Recommended Remediation
+[Copy recommendation from pentest report]
+
+## Our Remediation Plan
+[Describe specific steps we will take]
+
+## Acceptance Criteria
+- [ ] Vulnerability remediated
+- [ ] Verified by internal testing
+- [ ] Ready for re-test by penetration tester
+
+## Verification
+- [ ] Internal verification complete
+- [ ] Re-test requested from [Testing Firm]
+- [ ] Re-test passed
+
+## References
+- Full Report: [Link to pentest report in Notion]
+- Related CVEs: [If applicable]
+```

package/templates/SEC-VLN-vulnerability.md

@@ -0,0 +1,69 @@
+# SEC-VLN: Vulnerability Remediation
+
+## Quick Reference
+- **SLA:** 30-90 days (severity-based)
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Vulnerability Management
+
+## Required Labels
+- `Type: bug`
+- `Flag: security`
+- `Source: Vulnerability Scan` OR `Source: CodeQL` OR `Source: Penetration Test`
+- Severity label based on CVSS score
+
+## Severity to SLA Mapping
+| Severity | CVSS Score | Remediation SLA |
+|----------|------------|-----------------|
+| Critical | 9.0-10.0 | 30 days |
+| High | 7.0-8.9 | 30 days |
+| Medium | 4.0-6.9 | 60 days |
+| Low | 0.1-3.9 | 90 days |
+
+## Issue Template
+```markdown
+## Vulnerability Remediation
+
+**Vulnerability ID:** [CVE-XXXX-XXXXX or internal ID]
+**First Detected:** [YYYY-MM-DD]
+**Detection Source:** [Dependabot / CodeQL / AWS Inspector / Penetration Test / Manual]
+**Remediation Deadline:** [YYYY-MM-DD] (per SLA)
+
+## Vulnerability Details
+- **Affected Component:** [Package/library/system name]
+- **Current Version:** [x.x.x]
+- **Fixed Version:** [x.x.x] (if known)
+- **CVSS Score:** [X.X]
+- **Severity:** [Critical / High / Medium / Low]
+
+## Description
+[Brief description of the vulnerability and potential impact]
+
+## Affected Systems
+- [ ] Frontend
+- [ ] Backend (.NET)
+- [ ] AI Server (Python)
+- [ ] Infrastructure (AWS)
+
+## Business Impact Assessment
+[Describe potential business impact if exploited]
+
+## Proposed Remediation
+- [ ] Upgrade dependency to version [x.x.x]
+- [ ] Apply security patch
+- [ ] Configuration change
+- [ ] Code fix
+- [ ] Accept risk (requires documented justification)
+
+## Risk Treatment Plan (if SLA cannot be met)
+[Document justification and extended timeline if applicable]
+
+## Verification
+- [ ] Fix implemented
+- [ ] Re-scanned to confirm resolution
+- [ ] No regression in functionality
+
+## References
+- CVE Link: [URL]
+- Advisory: [URL]
+- Fix PR: [URL]
+```

package/templates/SLA-AVL-availability.md

@@ -0,0 +1,86 @@
+# SLA-AVL: Platform Availability Incident
+
+## Quick Reference
+- **SLA:** 1hr-14 days (severity-based)
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Availability Incidents
+
+## Severity Classification
+| Severity | Description | Response SLA | Resolution Target |
+|----------|-------------|--------------|-------------------|
+| Critical | Complete outage | 1 hour | 8 hours |
+| Medium | Core function impaired | 4 hours | 3 business days |
+| Low | Minor issues | 1 business day | 14 business days |
+
+## Required Labels
+- `Type: bug`
+- `Layer: [affected layer]`
+- Severity label based on impact
+
+## Issue Template
+```markdown
+## Platform Availability Incident
+
+**Incident ID:** SLA-AVL-YYYY-XXX
+**Start Time:** [YYYY-MM-DD HH:MM UTC]
+**Detection Time:** [YYYY-MM-DD HH:MM UTC]
+**Severity:** [Critical / Medium / Low]
+
+## Impact Assessment
+- **Services Affected:** [List affected services]
+- **Users Affected:** [All / Partial - describe scope]
+- **Customer Impact:** [Description of customer-facing impact]
+- **Workaround Available:** [Yes - describe / No]
+
+## Incident Description
+[Brief description of the outage/issue]
+
+## Timeline
+| Time (UTC) | Event |
+|------------|-------|
+| | Issue started |
+| | Issue detected |
+| | Investigation started |
+| | |
+
+## Investigation
+
+### Initial Assessment
+[What was observed, initial hypothesis]
+
+### Root Cause
+[If identified - otherwise "Under investigation"]
+
+### Affected Components
+- [ ] Frontend
+- [ ] Backend API
+- [ ] Database
+- [ ] AI Server
+- [ ] AWS Infrastructure
+- [ ] Third-party service: [Name]
+
+## Resolution
+
+### Actions Taken
+1. [Action 1]
+2. [Action 2]
+
+### Resolution Time
+- **Incident End Time:** [YYYY-MM-DD HH:MM UTC]
+- **Total Duration:** [X hours Y minutes]
+- **Resolution SLA Met:** [Yes / No]
+
+## Customer Communication
+- [ ] Status page updated
+- [ ] Affected customers notified
+- [ ] Resolution notification sent
+
+## Follow-up Required
+- [ ] Root Cause Analysis (create linked RCA-DOC if Critical/Medium)
+- [ ] Preventive measures identified
+- [ ] Post-mortem scheduled
+
+## SLA Credit Assessment
+- **Uptime this month:** [XX.XX%]
+- **Credit applicable:** [Yes - X% / No]
+```

package/templates/SLA-OPS-operational.md

@@ -0,0 +1,70 @@
+# SLA-OPS: Operational Request
+
+## Quick Reference
+- **SLA:** 3-14 days
+- **Team:** *the team that owns this workflow in your workspace*
+- **Project:** Operational Requests
+
+## Priority to SLA Mapping
+| Priority | Resolution Timeframe |
+|----------|---------------------|
+| High | 3 days |
+| Medium | 7 days |
+| Low | 14 days |
+
+## Required Labels
+- `Type: feature`
+- `Layer: devops`
+- `Infrastructure` (if infrastructure work)
+- `Account Setup` (if account work)
+
+## Issue Template
+```markdown
+## Operational Request
+
+**Request ID:** SLA-OPS-YYYY-XXX
+**Request Date:** [YYYY-MM-DD]
+**Requestor:** [Name]
+**Priority:** [High / Medium / Low]
+**SLA Deadline:** [YYYY-MM-DD]
+
+## Request Type
+- [ ] Infrastructure provisioning
+- [ ] Account setup
+- [ ] Configuration change
+- [ ] Access modification
+- [ ] Other: ___
+
+## Request Details
+[Detailed description of what is being requested]
+
+## Business Justification
+[Why is this request needed?]
+
+## Requirements
+[Specific technical requirements]
+
+## Dependencies
+- [ ] [Dependency 1]
+- [ ] [Dependency 2]
+
+## Implementation Plan
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Verification Criteria
+- [ ] [How to verify completion]
+
+## Approvals
+- [ ] Manager approval: _________________ Date: _______
+- [ ] Technical approval (if needed): _________________ Date: _______
+
+## Completion
+- [ ] Request fulfilled
+- [ ] Requestor notified
+- [ ] Documentation updated
+
+**Completion Date:** [YYYY-MM-DD]
+**SLA Met:** [Yes / No]
+```

package/templates/agent-server-template/README.md

@@ -0,0 +1,88 @@
+# Agent webhook receiver — reference template
+
+This directory is **a template, not a running server**. The Linear plugin is a CLI; it doesn't host long-running HTTP listeners. If you want the plugin to act as a Linear agent (the `actor=app` model where users `@mention` it or assign issues to it), you need to host this receiver somewhere — copy `server.example.ts` into your own project and adapt.
+
+## What it does
+
+1. Listens for `POST /linear/webhook` from Linear.
+2. Verifies the `linear-signature` HMAC-SHA256 header against the body using your stored signing secret.
+3. On `agentSessionEvent.created`, emits a `thought` activity within 10 seconds via the plugin's CLI to ack the session.
+4. Hands off to your actual agent logic (which you write).
+
+## Where to host
+
+| Host | Notes |
+|---|---|
+| Cloudflare Workers | Linear's own `linear/linear-agent-demo` uses Workers. Edit the example to use the Fetch API runtime. |
+| Vercel / Netlify functions | Fine for low traffic. Same Fetch API edits. |
+| Fly.io / Railway / Render | Run the example mostly as-is on Node. |
+| Local + ngrok | For dev only — Linear retries 3× on failure (1 min / 1 hr / 6 hr). |
+
+## Setup
+
+```bash
+# 1. Build the plugin CLI so the template can call it.
+npm install -g @elnora-ai/linear
+
+# 2. Copy this template into your own project.
+cp -r templates/agent-server-template /path/to/your/agent-server
+
+# 3. Register the webhook with Linear.
+linear webhooks create \
+  --url https://your-public-url/linear/webhook \
+  --resource-types AgentSessionEvent \
+  --all-public-teams
+# Save the secret it returns into LINEAR_WEBHOOK_SECRET.
+
+# 4. Run the receiver.
+LINEAR_API_KEY=lin_api_... \
+LINEAR_WEBHOOK_SECRET=lin_wh_... \
+node server.example.js
+```
+
+## What you fill in
+
+The template stops after acking the session. The real agent logic — running Claude Code, opening a PR, posting back to Linear — goes in the `// TODO` block. Common patterns:
+
+- **Quick echo bot:** emit a `response` activity with whatever you want to say.
+- **Coding agent:** `child_process.spawn` your dev workflow (e.g. `claude` + a prompt that includes the issue context).
+- **Triage routing:** read the issue, decide if it's for the bot, otherwise emit a `response` and exit.
+
+Use the CLI for everything Linear-side:
+
+```bash
+linear agent-activities create <sessionId> --type thought --body "Working on it"
+linear agent-activities create <sessionId> --type response --body "Done. PR: <url>"
+linear agent-sessions update-external-url <sessionId> --add https://github.com/.../pull/42
+```
+
+## Security notes
+
+- **Always** verify the signature before reading the body. The template ships an inline `verifyLinearWebhook` helper (HMAC-SHA256 + `timingSafeEqual`) — don't bypass it.
+- **Never** commit `LINEAR_WEBHOOK_SECRET` or `LINEAR_API_KEY`. Use your host's secret store.
+- **Rotate** the webhook secret with `linear webhooks rotate-secret <id> --yes` if you suspect a leak. The new secret is shown ONCE.
+- **Respond fast.** Linear retries on non-200 or >5s. ACK within 200ms by responding `200 ok` immediately, then doing the work async.
+
+## Activity types & lifecycle
+
+| Type | Body | When to use |
+|---|---|---|
+| `thought` | text | Internal narration, including the mandatory 10s ack |
+| `action` | `{action, parameter, result}` | Tool call summary (e.g. "ran `gh pr create`") |
+| `elicitation` | text + `signal` (`select` / `auth`) | Ask the user (multi-choice or auth URL) |
+| `response` | text | Final visible answer |
+| `error` | text | Visible failure message |
+
+The session is considered "stale" after 30 minutes of inactivity but is recoverable — emit any activity to revive.
+
+## Troubleshooting
+
+- **401 in your logs**: signature mismatch. Check `LINEAR_WEBHOOK_SECRET` matches what `linear webhooks list` shows.
+- **No webhook delivered**: confirm `agentSessionEvent` is in the webhook's `resourceTypes`.
+- **"Agent unresponsive" in Linear UI**: you took longer than 10s to emit a thought. Move the ack BEFORE any expensive work.
+
+## See also
+
+- Plugin CLI: `linear webhooks --help`, `linear agent-sessions --help`, `linear agent-activities --help`
+- Linear's official agent docs: https://linear.app/developers/agents
+- Linear's reference Cloudflare-Worker demo: https://github.com/linear/linear-agent-demo

package/templates/agent-server-template/server.example.ts

@@ -0,0 +1,185 @@
+/**
+ * Reference webhook receiver for Linear's agent framework.
+ *
+ * This is a TEMPLATE — it ships with the plugin so operators can run their
+ * own agent receiver wherever they want (Cloudflare Worker, Vercel function,
+ * Fly machine, etc.). The plugin itself is a CLI; it does not host this
+ * server for you.
+ *
+ *   1. Register a webhook in Linear pointing at this server's URL:
+ *        linear webhooks create \
+ *          --url https://your-host/linear/webhook \
+ *          --resource-types AgentSessionEvent \
+ *          --all-public-teams
+ *      (Linear will return a signing secret — store as LINEAR_WEBHOOK_SECRET.)
+ *
+ *   2. Run this server with both env vars set:
+ *        LINEAR_API_KEY=lin_api_... \
+ *        LINEAR_WEBHOOK_SECRET=lin_wh_... \
+ *        node server.example.js
+ *
+ *   3. Linear delivers `agentSessionEvent` POSTs to /linear/webhook. We
+ *      verify the signature, then must emit a `thought` activity within
+ *      10 seconds to acknowledge.
+ *
+ * The activity-create call shells out to the plugin's CLI so you don't end
+ * up with two implementations. The signature verifier is inlined below so
+ * this file works after `cp -r` out of the plugin tree — no relative
+ * imports back into the plugin source.
+ */
+
+import http from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Verify a Linear webhook payload's HMAC-SHA256 signature AND its replay
+ * window. Mirrors the implementation in the plugin's webhook-verify util —
+ * kept inline so this template stands alone after copy.
+ *
+ * Replay protection: when `timestamp` (the `webhookTimestamp` field from the
+ * parsed body, Unix ms) is provided, payloads older than `maxAgeMs` are
+ * rejected. Without this, an attacker who captures a valid signed request
+ * can replay it forever.
+ */
+// Linear recommends 60 s — see https://linear.app/developers/webhooks
+const DEFAULT_WEBHOOK_MAX_AGE_MS = 60 * 1000;
+
+function verifyLinearWebhook(opts: {
+  rawBody: string | Buffer;
+  signature: string;
+  secret: string;
+  timestamp?: number;
+  maxAgeMs?: number;
+}): boolean {
+  if (!opts.signature || !opts.secret) return false;
+  const body = typeof opts.rawBody === "string" ? Buffer.from(opts.rawBody, "utf-8") : opts.rawBody;
+  const expectedHex = createHmac("sha256", opts.secret).update(body).digest("hex");
+  const expected = Buffer.from(expectedHex, "hex");
+  let received: Buffer;
+  try {
+    received = Buffer.from(opts.signature, "hex");
+  } catch {
+    return false;
+  }
+  if (received.length !== expected.length) return false;
+  if (!timingSafeEqual(received, expected)) return false;
+
+  if (typeof opts.timestamp === "number") {
+    if (!Number.isFinite(opts.timestamp)) return false;
+    const maxAgeMs = opts.maxAgeMs ?? DEFAULT_WEBHOOK_MAX_AGE_MS;
+    if (Math.abs(Date.now() - opts.timestamp) > maxAgeMs) return false;
+  }
+  return true;
+}
+
+const PORT = Number(process.env.PORT ?? 8787);
+const SECRET = process.env.LINEAR_WEBHOOK_SECRET;
+const CLI_PATH = process.env.LINEAR_CLI_PATH ?? "../../cli/bin/linear.js";
+
+if (!SECRET) {
+  console.error("LINEAR_WEBHOOK_SECRET not set — refusing to start.");
+  process.exit(1);
+}
+if (!process.env.LINEAR_API_KEY) {
+  console.error("LINEAR_API_KEY not set — refusing to start.");
+  process.exit(1);
+}
+
+interface AgentSessionEvent {
+  type: "AgentSessionEvent";
+  action: "created" | "prompted";
+  agentSession?: { id: string; type?: string };
+  promptContext?: string;
+}
+
+async function readBody(req: http.IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** Emit a thought activity via the CLI (one process per call — fine for ack). */
+async function emitThought(sessionId: string, body: string): Promise<void> {
+  await execFileAsync("node", [
+    CLI_PATH,
+    "agent-activities", "create", sessionId,
+    "--type", "thought",
+    "--body", body,
+  ]);
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.method !== "POST" || req.url !== "/linear/webhook") {
+    res.writeHead(404);
+    res.end();
+    return;
+  }
+  const signature = req.headers["linear-signature"];
+  if (typeof signature !== "string") {
+    res.writeHead(400);
+    res.end("Missing linear-signature header");
+    return;
+  }
+  const rawBody = await readBody(req);
+  // HMAC-verify on the raw bytes BEFORE touching JSON.parse — never let
+  // unverified input reach the parser. Replay-window check happens after,
+  // once we trust the body enough to read webhookTimestamp out of it.
+  if (!verifyLinearWebhook({ rawBody, signature, secret: SECRET })) {
+    res.writeHead(401);
+    res.end("Invalid signature");
+    return;
+  }
+  let parsedForTimestamp: { webhookTimestamp?: number } = {};
+  try {
+    parsedForTimestamp = JSON.parse(rawBody.toString("utf-8"));
+  } catch {
+    res.writeHead(400);
+    res.end("Body is not valid JSON");
+    return;
+  }
+  const timestamp = parsedForTimestamp.webhookTimestamp;
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+    res.writeHead(401);
+    res.end("Missing or invalid webhookTimestamp");
+    return;
+  }
+  if (Math.abs(Date.now() - timestamp) > DEFAULT_WEBHOOK_MAX_AGE_MS) {
+    res.writeHead(401);
+    res.end("Expired payload");
+    return;
+  }
+  // ACK Linear within 5s — non-200 triggers a retry and counts against agent
+  // responsiveness. Do work async after responding.
+  res.writeHead(200);
+  res.end("ok");
+
+  const payload = JSON.parse(rawBody.toString("utf-8")) as AgentSessionEvent;
+  if (payload.type !== "AgentSessionEvent") return;
+  if (payload.action !== "created") return;
+  const sessionId = payload.agentSession?.id;
+  if (!sessionId) return;
+
+  // Linear requires a thought within 10s — emit immediately then start work.
+  try {
+    await emitThought(sessionId, "Got it — picking this up now.");
+  } catch (e) {
+    console.error("Failed to emit ack thought:", e);
+    return;
+  }
+
+  // TODO: kick off whatever the agent actually does. Examples:
+  //  - Run /linear-work as a subprocess (background coding agent)
+  //  - Trigger your own task queue
+  //  - Update the issue with progress via `linear issues update`
+  console.log(`[agent] session ${sessionId} acknowledged`);
+});
+
+server.listen(PORT, () => {
+  console.log(`Linear agent webhook receiver listening on :${PORT}/linear/webhook`);
+});