open-index/open-npm huggingface dataset:
npm package: @sanity-labs/backstage-plugin-socket-backend
Description: Backend plugin for the Socket.dev security integration. This plugin provides a REST API for fetching Socket.dev security reports with server-side caching.
Latest version: 1.0.2

# Socket Backend Plugin

Backend plugin for the Socket.dev security integration. This plugin provides a REST API for fetching Socket.dev security reports with server-side caching.

> **Note:** This is the backend companion to [@sanity-labs/backstage-plugin-socket](../socket). Both packages are required for full functionality.

## Installation

```bash
# From your Backstage root directory
yarn --cwd packages/backend add @sanity-labs/backstage-plugin-socket-backend
```

## Setup

1. Add the plugin to your backend in `packages/backend/src/index.ts`:

```typescript
backend.add(import('@sanity-labs/backstage-plugin-socket-backend'));
```

2. Configure in `app-config.yaml`:

```yaml
socket:
  apiToken: ${SOCKET_API_TOKEN}  # Required - Socket.dev API token
  cacheTime: 5                    # Optional - Backend cache TTL in minutes (default: 5)
  apiBaseUrl: https://api.socket.dev  # Optional - Socket API base URL (default: https://api.socket.dev)
```

3. Set environment variable:

**Option 1: Using .env file (recommended for local development)**

Create a `.env` file in the root of your project:
```bash
SOCKET_API_TOKEN=your-socket-api-token
```

Then run the development servers with the dotenv wrapper:
```bash
yarn dev
```

The `dev` script uses `dotenv-cli` to automatically load variables from `.env`.

**Option 2: Export environment variable**
```bash
export SOCKET_API_TOKEN=your-socket-api-token
yarn start-backend
```

**Note:** A `.env.example` file is provided in the repository root as a template.

## API Endpoints

### GET /api/socket/health

Health check endpoint with cache statistics.

**Response:**
```json
{
  "status": "ok",
  "cache": {
    "size": 3,
    "keys": ["report-owner/repo"]
  },
  "config": {
    "apiBaseUrl": "https://api.socket.dev",
    "cacheTime": 5,
    "hasApiToken": true
  }
}
```

### GET /api/socket/reports/:repo/latest

Get the latest security report for a repository.

**Parameters:**
- `repo` (path): Repository in format `owner/repo` (URL-encoded)

**Example:**
```bash
curl http://localhost:7007/api/socket/reports/owner%2Frepo/latest
```

**Response:**
```json
{
  "repository": "owner/repo",
  "findings": [...],
  "totalFindings": 10,
  "criticalFindings": 2,
  "highFindings": 3,
  "mediumFindings": 5,
  "lowFindings": 0,
  "scannedAt": "2024-01-01T00:00:00Z",
  "cachedAt": "2024-01-01T00:05:00Z"
}
```

## Caching

The backend implements TTL-based in-memory caching to reduce Socket.dev API calls:
- Default cache TTL: 5 minutes
- Cache key format: `report-{repository}`
- Cache automatically expires stale entries

## Development

Build:
```bash
yarn tsc
yarn build
```

Test:
```bash
yarn test
```

Lint:
```bash
yarn lint
```