Skip to content

secondsky/claude-skills / plugins/cloudflare-images/skills/cloudflare-images

cloudflare-images

Unverified

This skill should be used when the user asks to "upload images to Cloudflare", "implement direct creator upload", "configure image transformations", "optimize WebP/AVIF", "create image variants", "generate signed URLs", "add image watermarks", "integrate with Next.js/Remix", "configure webhooks", "debug CORS errors", "troubleshoot error 5408/9401-9413", or "build responsive images with Cloudflare Images API".

FileKindSize
SKILL.mdskill md13.9 KB
assets/diagrams/direct-upload-workflow.mdmarkdown5.0 KB
assets/diagrams/transformation-pipeline.mdmarkdown8.2 KB
assets/diagrams/variants-structure.mdmarkdown10.6 KB
examples/basic-upload/.env.exampleother474 B
examples/basic-upload/README.mdmarkdown6.5 KB
examples/basic-upload/package.jsonmanifest542 B
examples/basic-upload/public/index.htmlother12.7 KB
examples/basic-upload/src/index.tsscript2.7 KB
examples/basic-upload/wrangler.jsoncother378 B
examples/private-images/.env.exampleother631 B
examples/private-images/README.mdmarkdown12.5 KB
examples/private-images/package.jsonmanifest741 B
examples/private-images/public/index.htmlother18.0 KB
examples/private-images/src/index.tsscript5.2 KB
examples/private-images/wrangler.jsoncother427 B
examples/responsive-gallery/README.mdmarkdown4.3 KB
references/api-reference.mdmarkdown8.1 KB
references/content-credentials.mdmarkdown11.6 KB
references/custom-domains.mdmarkdown10.5 KB
references/direct-upload-complete-workflow.mdmarkdown11.2 KB
references/format-optimization.mdmarkdown7.2 KB
references/framework-integration.mdmarkdown15.4 KB
references/overlays-watermarks.mdmarkdown11.1 KB
references/polish-compression.mdmarkdown10.4 KB
references/responsive-images-patterns.mdmarkdown6.1 KB
references/setup-guide.mdmarkdown3.8 KB
references/signed-urls-guide.mdmarkdown7.5 KB
references/sourcing-kit.mdmarkdown15.0 KB
references/top-errors.mdmarkdown11.7 KB
references/transformation-options.mdmarkdown6.4 KB
references/variants-guide.mdmarkdown6.7 KB
references/webhooks-guide.mdmarkdown11.8 KB
scripts/analyze-usage.shexecutablescript6.6 KB
scripts/check-versions.shexecutablescript3.3 KB
scripts/generate-signed-url.shexecutablescript4.4 KB
scripts/test-upload.shexecutablescript4.4 KB
scripts/validate-variants.shexecutablescript5.2 KB
templates/batch-upload.tsscript7.8 KB
templates/direct-creator-upload-backend.tsscript5.4 KB
templates/direct-creator-upload-frontend.htmlother8.4 KB
templates/nextjs-integration.tsxother11.4 KB
templates/overlay-watermark.tsscript13.7 KB
templates/package.jsonmanifest387 B
templates/remix-integration.tsxother15.0 KB
templates/responsive-images-srcset.htmlother8.0 KB
templates/signed-urls-generation.tsscript6.6 KB
templates/transform-via-url.tsscript6.5 KB
templates/transform-via-workers.tsscript8.7 KB
templates/upload-api-basic.tsscript3.8 KB
templates/upload-via-url.tsscript4.9 KB
templates/variants-management.tsscript7.0 KB
templates/webhook-handler.tsscript8.8 KB
templates/wrangler-images-binding.jsoncother1.2 KB

references/signed-urls-guide.md

View on GitHub
# Signed URLs Guide

Complete guide to generating signed URLs for private images using HMAC-SHA256.

---

## What Are Signed URLs?

Time-limited URLs for serving private images securely.

**Format**:
```
https://imagedelivery.net/<HASH>/<ID>/<VARIANT>?exp=<EXPIRY>&sig=<SIGNATURE>
```

**Use cases**:
- User profile photos (private until shared)
- Paid content (time-limited access)
- Temporary downloads
- Secure image delivery

---

## Requirements

1. **Upload with signed URLs enabled**:
```javascript
await uploadImage(file, {
  requireSignedURLs: true // Image requires signed URL
});
```

2. **Get signing key**:
Dashboard → Images → Keys → Generate key

3. **Use named variants only**:
Flexible variants NOT compatible with signed URLs.

---

## Signature Algorithm (HMAC-SHA256)

### String to Sign

```
{imageId}{variant}{expiry}
```

**Example**:
```
Image ID: abc123
Variant: public
Expiry: 1735228800

String to sign: abc123public1735228800
```

### Generate Signature

**Workers** (recommended):
```typescript
async function generateSignature(
  imageId: string,
  variant: string,
  expiry: number,
  signingKey: string
): Promise<string> {
  const stringToSign = `${imageId}${variant}${expiry}`;

  const encoder = new TextEncoder();
  const keyData = encoder.encode(signingKey);
  const messageData = encoder.encode(stringToSign);

  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    keyData,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signature = await crypto.subtle.sign('HMAC', cryptoKey, messageData);

  // Convert to hex string
  return Array.from(new Uint8Array(signature))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}
```

**Node.js**:
```javascript
const crypto = require('crypto');

function generateSignature(imageId, variant, expiry, signingKey) {
  const stringToSign = `${imageId}${variant}${expiry}`;

  return crypto
    .createHmac('sha256', signingKey)
    .update(stringToSign)
    .digest('hex');
}
```

### Build Signed URL

```typescript
async function generateSignedURL(
  imageId: string,
  variant: string,
  expirySeconds: number,
  accountHash: string,
  signingKey: string
): Promise<string> {
  const expiry = Math.floor(Date.now() / 1000) + expirySeconds;
  const sig = await generateSignature(imageId, variant, expiry, signingKey);

  return `https://imagedelivery.net/${accountHash}/${imageId}/${variant}?exp=${expiry}&sig=${sig}`;
}
```

---

## Expiry Timestamp

**Unix timestamp** (seconds since epoch):
```typescript
const now = Math.floor(Date.now() / 1000);
const oneHour = 60 * 60;
const expiry = now + oneHour; // 1 hour from now
```

**From specific date**:
```typescript
const expiryDate = new Date('2025-10-27T18:00:00Z');
const expiry = Math.floor(expiryDate.getTime() / 1000);
```

**Common presets**:
```typescript
const expiryPresets = {
  fiveMinutes: 5 * 60,
  fifteenMinutes: 15 * 60,
  oneHour: 60 * 60,
  oneDay: 24 * 60 * 60,
  oneWeek: 7 * 24 * 60 * 60
};
```

---

## Complete Example (Workers)

```typescript
interface Env {
  IMAGES_ACCOUNT_HASH: string;
  IMAGES_SIGNING_KEY: string;
}

async function generateSignedURL(
  imageId: string,
  variant: string,
  expirySeconds: number,
  env: Env
): Promise<string> {
  const now = Math.floor(Date.now() / 1000);
  const expiry = now + expirySeconds;
  const stringToSign = `${imageId}${variant}${expiry}`;

  const encoder = new TextEncoder();
  const keyData = encoder.encode(env.IMAGES_SIGNING_KEY);
  const messageData = encoder.encode(stringToSign);

  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    keyData,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signature = await crypto.subtle.sign('HMAC', cryptoKey, messageData);
  const sig = Array.from(new Uint8Array(signature))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');

  return `https://imagedelivery.net/${env.IMAGES_ACCOUNT_HASH}/${imageId}/${variant}?exp=${expiry}&sig=${sig}`;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Generate signed URL valid for 1 hour
    const signedURL = await generateSignedURL(
      'image-id',
      'public',
      3600,
      env
    );

    return Response.json({ signedURL });
  }
};
```

---

## Multiple Variants

Generate signed URLs for multiple variants at once:

```typescript
async function generateSignedURLsForVariants(
  imageId: string,
  variants: string[],
  expirySeconds: number,
  env: Env
): Promise<Record<string, string>> {
  const urls: Record<string, string> = {};

  for (const variant of variants) {
    urls[variant] = await generateSignedURL(imageId, variant, expirySeconds, env);
  }

  return urls;
}

// Usage
const urls = await generateSignedURLsForVariants(
  'image-id',
  ['thumbnail', 'medium', 'large'],
  3600,
  env
);

// {
//   thumbnail: 'https://imagedelivery.net/.../thumbnail?exp=...&sig=...',
//   medium: 'https://imagedelivery.net/.../medium?exp=...&sig=...',
//   large: 'https://imagedelivery.net/.../large?exp=...&sig=...'
// }
```

---

## Verification (Cloudflare handles this)

For reference, here's how verification works:

```typescript
async function verifySignature(
  imageId: string,
  variant: string,
  expiry: number,
  providedSig: string,
  signingKey: string
): Promise<boolean> {
  // Check if expired
  const now = Math.floor(Date.now() / 1000);
  if (expiry < now) {
    return false; // Expired
  }

  // Generate expected signature
  const expectedSig = await generateSignature(imageId, variant, expiry, signingKey);

  return expectedSig === providedSig;
}
```

---

## Common Issues

### 1. Signed URL returns 403

**Causes**:
- Image not uploaded with `requireSignedURLs=true`
- Signature incorrect (wrong signing key)
- URL expired
- Using flexible variants (not supported)

**Solutions**:
- Verify image requires signed URLs
- Check signing key matches dashboard
- Ensure expiry in future
- Use named variants only

### 2. Signature doesn't match

**Causes**:
- Wrong signing key
- Incorrect string-to-sign format
- Timestamp precision (must be seconds, not milliseconds)

**Solutions**:
```typescript
// ✅ CORRECT - Seconds
const expiry = Math.floor(Date.now() / 1000);

// ❌ WRONG - Milliseconds
const expiry = Date.now();
```

### 3. Cannot use with flexible variants

**Error**: 403 Forbidden when using flexible variants with signed URLs

**Solution**: Use named variants for private images
```typescript
// ✅ CORRECT
const url = await generateSignedURL('id', 'thumbnail', 3600, env);

// ❌ WRONG
const url = `https://imagedelivery.net/${hash}/${id}/w=300?exp=${exp}&sig=${sig}`;
```

---

## Security Best Practices

1. **Keep signing key secret**: Never expose in client-side code
2. **Generate on backend**: Frontend requests signed URL from backend
3. **Short expiry for sensitive content**: 5-15 minutes for temporary access
4. **Longer expiry for user content**: 1-24 hours for profile photos
5. **Rotate keys periodically**: Dashboard → Images → Keys → Regenerate
6. **Log suspicious activity**: Monitor for signature mismatches

---

## Example Use Cases

### Profile Photos (24-hour expiry)
```typescript
const profileURL = await generateSignedURL('user-123', 'avatar', 24 * 60 * 60, env);
```

### Temporary Download (5 minutes)
```typescript
const downloadURL = await generateSignedURL('doc-456', 'large', 5 * 60, env);
```

### Paid Content (1-week subscription)
```typescript
const contentURL = await generateSignedURL('premium-789', 'medium', 7 * 24 * 60 * 60, env);
```

---

## Official Documentation

- **Serve Private Images**: https://developers.cloudflare.com/images/manage-images/serve-images/serve-private-images/
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall