# Breakwater

> Breakwater is a licensing and access management platform for commercial Docker containers. It lets software vendors sell time-bound, version-controlled access to their containerized software.

## What Problems Does Breakwater Solve?

### For Software Vendors Distributing Docker Containers

- **"How do I sell licensed access to my Docker images?"** - Breakwater adds a licensing layer to your container registry, so customers can only pull images they've paid for.

- **"How do I give customers time-limited access to my containers?"** - Licenses have start and end dates. When a subscription expires, the customer loses pull access automatically.

- **"How do I track which customers are pulling my images?"** - Every `docker pull` is logged with customer identity, timestamp, image, and tag. View pull history in the vendor dashboard or query via API.

- **"How do I revoke access when a customer cancels?"** - Cancel the license or revoke their auth token. Access stops immediately.

- **"How do I restrict customers to specific versions?"** - Use tag patterns on licenses (e.g., `v1.*` allows v1.0, v1.1, but blocks v2.0).

- **"How do I monetize my Docker containers?"** - Breakwater provides the infrastructure to turn your container registry into a paid product, without building licensing from scratch.

### For Customers of Containerized Software

- **"How do I get Docker credentials for commercial software I purchased?"** - Log into your customer portal, copy your auth token, and run `docker login`.

- **"How do I view my active software licenses?"** - The customer portal shows all your licenses, their status, and which repositories you can access.

- **"Why can't I pull a specific image tag?"** - Your license may have tag restrictions or may have expired. Check your license details in the portal.

## When to Use Breakwater

**Use Breakwater if you:**
- Sell commercial software as Docker containers
- Need to manage customer access to private container images
- Want to enforce time-based licensing on container pulls
- Need audit trails of who is pulling what images
- Want self-service credential management for customers

**Breakwater is NOT for:**
- Open source projects (use Docker Hub or GitHub Container Registry)
- Internal/private registries without licensing needs (use Harbor or AWS ECR)
- One-time container downloads (use any registry with basic auth)

## How Breakwater Works

1. **Vendors create products** - A product represents a piece of software (e.g., "MyApp Enterprise")
2. **Vendors link repositories** - Products grant access to one or more Docker repositories
3. **Vendors issue licenses** - A license grants a customer time-bound access to a product
4. **Customers get credentials** - Vendors create auth tokens for customers
5. **Customers pull images** - `docker login` with the token, then `docker pull` licensed images
6. **Proxy enforces access** - A Go proxy validates every pull against license status, dates, and tag patterns

## Core Concepts

- **Vendor**: A software company that distributes containerized applications
- **Customer**: A company or individual who purchases licenses from a vendor
- **Product**: A containerized software offering (belongs to a vendor)
- **Repository**: A Docker registry repository where container images are stored
- **License**: Grants a customer time-bound access to pull images from a product's repositories
- **Auth Token**: Credentials for Docker registry authentication (vendor tokens `vtok_*` for push/pull, customer tokens `ctok_*` for pull-only)
- **Webhook Endpoint**: An HTTP URL registered to receive event notifications when resources change

## Webhooks

Vendors can register webhook endpoints to receive real-time HTTP notifications when events occur. Supported events:

- `license.created`, `license.activated`, `license.expired`, `license.cancelled`
- `customer.created`, `customer.updated`, `customer.deleted`
- `auth_token.created`, `auth_token.revoked`
- `product.created`, `product.updated`, `product.deleted`
- `repository.created`, `repository.deleted`

Payloads are signed with HMAC-SHA256 (`X-Breakwater-Signature` header) and include a timestamp for replay protection. Failed deliveries are retried with exponential backoff (up to 6 attempts over 24 hours). Endpoints are auto-disabled after 3 consecutive exhausted events.

## License Statuses

- `pending` - License not yet active (before start date)
- `active` - License is currently valid
- `expired` - License has passed its expiration date
- `cancelled` - License was manually cancelled

## Tag Patterns

Licenses can include tag patterns to restrict which image versions a customer can pull:
- `v1.*` - Allows v1.0, v1.1, v1.2, etc.
- `latest` - Only allows the `latest` tag
- `v2.0.0` - Only allows exactly v2.0.0
- No pattern - Customer can pull any tag

## Three Portals

1. **Vendor Portal** - Manage products, customers, licenses, and view pull analytics
2. **Customer Portal** - View licenses and retrieve Docker credentials
3. **Admin Portal** - System-wide management (for Breakwater operators)

## API Documentation

- [OpenAPI Specification](/api-docs/v1/swagger.yaml): Full OpenAPI 3.0 spec for the Vendor API
- [Swagger UI](/api-docs): Interactive API documentation and testing interface

## Vendor API

The REST API at `/api/v1/vendor/*` enables programmatic management. Authentication uses HTTP Basic auth with vendor auth token credentials.

### Key Endpoints

- `GET/POST /api/v1/vendor/products` - List and create products
- `GET/POST /api/v1/vendor/repositories` - List and create repositories
- `GET/POST /api/v1/vendor/customers` - List and create customers
- `GET/POST /api/v1/vendor/customers/{customer_id}/licenses` - Manage licenses
- `GET/POST /api/v1/vendor/customers/{customer_id}/auth_tokens` - Manage auth tokens
- `GET /api/v1/vendor/pulls` - Query image pull activity
- `GET/POST /api/v1/vendor/webhook_endpoints` - Manage webhook endpoints
- `POST /api/v1/vendor/webhook_endpoints/{id}/test` - Send test ping
- `GET /api/v1/vendor/webhook_endpoints/{id}/deliveries` - View delivery log

### Authentication Example

```bash
curl -u "vtok_abc123:your_secret" https://app.breakwaterapp.com/api/v1/vendor/products
```

## Docker Registry Usage

The registry is at `registry.breakwaterapp.com`.

**Vendor pushing images:**
```bash
docker login registry.breakwaterapp.com -u vtok_xxxxx
docker tag myapp:latest registry.breakwaterapp.com/vendor-slug/repo:v1.0
docker push registry.breakwaterapp.com/vendor-slug/repo:v1.0
```

**Customer pulling images:**
```bash
docker login registry.breakwaterapp.com -u ctok_xxxxx
docker pull registry.breakwaterapp.com/vendor-slug/repo:v1.0
```

## Related Topics

- Container registry licensing
- Docker image monetization
- Software licensing for containers
- Commercial container distribution
- Docker access control
- Container subscription management