linear-security-basics
Secure API key management and OAuth best practices for Linear. Use when setting up authentication securely, implementing OAuth flows, or hardening Linear integrations. Trigger with phrases like "linear security", "linear API key security", "linear OAuth", "secure linear integration", "linear secrets management".
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 2.0k
- Forks
- 233
01 前言 Front Matter
- name
- linear-security-basics
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Secure API key management and OAuth best practices for Linear. Use when setting up authentication securely, implementing OAuth flows, or hardening Linear integrations. Trigger with phrases like "linear security", "linear API key security", "linear OAuth", "secure linear integration", "linear secrets management".
- allowed-tools
- Read, Write, Edit, Grep
03 SKILL.md 正文
Linear Security Basics
Overview
Implement secure authentication and API key management for Linear integrations.
Prerequisites
- Linear account with API access
- Understanding of environment variables
- Familiarity with OAuth 2.0 concepts
Instructions
Step 1: Secure API Key Storage
Never hardcode API keys:
// BAD - Never do this!
const client = new LinearClient({
apiKey: "lin_api_xxxxxxxxxxxx" // Exposed in source code
});
// GOOD - Use environment variables
const client = new LinearClient({
apiKey: process.env.LINEAR_API_KEY!
});
Environment Setup:
# .env (never commit this file)
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
# .gitignore (commit this)
.env
.env.*
!.env.example
# .env.example (commit this for documentation)
LINEAR_API_KEY=lin_api_your_key_here
Validate on Startup:
// config/linear.ts
function validateConfig(): void {
const apiKey = process.env.LINEAR_API_KEY;
if (!apiKey) {
throw new Error("LINEAR_API_KEY environment variable is required");
}
if (!apiKey.startsWith("lin_api_")) {
throw new Error("LINEAR_API_KEY has invalid format");
}
if (apiKey.length < 30) {
throw new Error("LINEAR_API_KEY appears too short");
}
}
validateConfig();
Step 2: Implement OAuth 2.0 Flow
// For user-facing applications
import express from "express";
import crypto from "crypto";
const app = express();
// OAuth configuration
const OAUTH_CONFIG = {
clientId: process.env.LINEAR_CLIENT_ID!,
clientSecret: process.env.LINEAR_CLIENT_SECRET!,
redirectUri: process.env.LINEAR_REDIRECT_URI!,
scope: ["read", "write", "issues:create"],
};
// Step 1: Initiate OAuth
app.get("/auth/linear", (req, res) => {
const state = crypto.randomBytes(16).toString("hex");
req.session!.oauthState = state;
const authUrl = new URL("https://linear.app/oauth/authorize");
authUrl.searchParams.set("client_id", OAUTH_CONFIG.clientId);
authUrl.searchParams.set("redirect_uri", OAUTH_CONFIG.redirectUri);
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", OAUTH_CONFIG.scope.join(","));
authUrl.searchParams.set("state", state);
res.redirect(authUrl.toString());
});
// Step 2: Handle callback
app.get("/auth/linear/callback", async (req, res) => {
const { code, state } = req.query;
// Verify state to prevent CSRF
if (state !== req.session!.oauthState) {
return res.status(400).json({ error: "Invalid state parameter" });
}
// Exchange code for tokens
const response = await fetch("https://api.linear.app/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
code: code as string,
client_id: OAUTH_CONFIG.clientId,
client_secret: OAUTH_CONFIG.clientSecret,
redirect_uri: OAUTH_CONFIG.redirectUri,
}),
});
const tokens = await response.json();
// Store tokens securely (encrypted in database)
await storeTokens(req.user!.id, {
accessToken: encrypt(tokens.access_token),
refreshToken: encrypt(tokens.refresh_token),
expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
});
res.redirect("/dashboard");
});
Step 3: Token Refresh Flow
async function getValidAccessToken(userId: string): Promise<string> {
const stored = await getStoredTokens(userId);
// Check if token is expired or expiring soon (5 min buffer)
if (stored.expiresAt.getTime() - Date.now() < 5 * 60 * 1000) {
const response = await fetch("https://api.linear.app/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
refresh_token: decrypt(stored.refreshToken),
client_id: process.env.LINEAR_CLIENT_ID!,
client_secret: process.env.LINEAR_CLIENT_SECRET!,
}),
});
const tokens = await response.json();
await storeTokens(userId, {
accessToken: encrypt(tokens.access_token),
refreshToken: encrypt(tokens.refresh_token),
expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
});
return tokens.access_token;
}
return decrypt(stored.accessToken);
}
Step 4: Webhook Signature Verification
import crypto from "crypto";
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expectedSignature = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
// Use timing-safe comparison to prevent timing attacks
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Express middleware
app.post("/webhooks/linear", express.raw({ type: "*/*" }), (req, res) => {
const signature = req.headers["linear-signature"] as string;
const payload = req.body.toString();
if (!verifyWebhookSignature(payload, signature, process.env.LINEAR_WEBHOOK_SECRET!)) {
return res.status(401).json({ error: "Invalid signature" });
}
const event = JSON.parse(payload);
// Process verified webhook...
res.status(200).json({ received: true });
});
Step 5: Secret Rotation
// Support multiple API keys during rotation
const apiKeys = [
process.env.LINEAR_API_KEY_NEW,
process.env.LINEAR_API_KEY_OLD,
].filter(Boolean);
async function getWorkingClient(): Promise<LinearClient> {
for (const apiKey of apiKeys) {
try {
const client = new LinearClient({ apiKey: apiKey! });
await client.viewer; // Test the key
return client;
} catch {
continue;
}
}
throw new Error("No valid Linear API key found");
}
Security Checklist
- [ ] API keys stored in environment variables only
- [ ] .env files in .gitignore
- [ ] OAuth state parameter validated
- [ ] Tokens encrypted at rest
- [ ] Token refresh implemented
- [ ] Webhook signatures verified
- [ ] HTTPS enforced for all endpoints
- [ ] API keys rotated periodically
- [ ] Minimal OAuth scopes requested
Error Handling
| Error | Cause | Solution |
|---|---|---|
Invalid signature |
Webhook secret mismatch | Verify secret matches Linear settings |
Token expired |
Refresh token expired | Re-authorize user |
Invalid scope |
Missing permission | Request additional scopes |
Resources
Next Steps
Prepare for production with linear-prod-checklist.
04 同仓库更多 Skills
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
neuropixels-analysis
Neuropixels neural recording analysis. Load SpikeGLX/OpenEphys data, preprocess, motion correction, Kilosort4 spike sorting, quality metrics, Allen/IBL curation, AI-assisted visual analysis, for Neuropixels 1.0/2.0 extracellular electrophysiology. Use when working with neural recordings, spike sorting, extracellular electrophysiology, or when the user mentions Neuropixels, SpikeGLX, Open Ephys, Kilosort, quality metrics, or unit curation.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
notebooklm
Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.