@core / media

1.1.0 ▾

1.1.0

verifiziertMIT

GitHub

Medienbibliothek: signierte Direkt-Uploads, echte Typprüfung, EXIF/GPS entfernt, Alt-Text, Fokuspunkt, srcset

Code13 DateienKontext~777 TokensPrüfung bestanden

~777 Tokens→ src/lib/media/AGENTS.md→ .cursor/rules/genpm-core-media.mdc

Genau das liest deine KI, wenn sie in src/lib/media arbeitet. Sonst wird ihrem Kontext nichts hinzugefügt.

@core/media — rules for AI agents

Purpose

Media library on top of @core/storage: the browser uploads directly with a signed URL to a private staging key (uploads/pending/<id>.<ext>), then confirmUpload checks the real file type by its bytes (declared type must match), removes EXIF/GPS/XMP from JPEG, PNG and WebP without re-encoding, writes the validated bytes to the final public/ key, deletes the staging copy and stores dimensions. Malformed images (chunk lengths past the end) are rejected. Alt text and focal point per file, responsive URLs (Cloudflare Images or Next.js image optimizer) and ready <img> attributes. SVG and HTML are never accepted. Table: media.

Map

index.ts — public API: createUpload, confirmUpload, getMedia, updateMedia, deleteMedia, imageUrl, imgAttrs, mediaAdminResource.
remote.ts — importRemoteImage(url, { allowedHosts }) for server-side imports (https, host allowlist, size limit).
library.ts — upload flow, allowed types and stagingKey(media). sniff.ts, strip.ts — byte checks. urls.ts — URLs and <img> attributes.
adapters/hono.ts — mediaRoutes({ authorize }). adapters/next.ts — createUploadRoute, confirmUploadRoute.

Integration

Configure @core/storage first (bucket CORS must allow PUT from the site). Recommended: a bucket lifecycle rule that deletes uploads/pending/ objects after 1 day (abandoned or replayed uploads). Optional MEDIA_TRANSFORM: cloudflare (Images transformations enabled on the zone), vercel (Next.js image optimizer; add the storage host to images.remotePatterns) or none.
Migrations as in src/lib/db/AGENTS.md.
Mount the upload routes with an authorize(req) that returns { userId } only for users with media:create (@core/rbac).
Upload from the browser: POST /api/media/uploads with { filename, mime, size } → PUT the file to upload.url with upload.headers → POST /api/media/uploads/<id>/confirm. Store the media id in your content.
Render: const m = await getMedia(id); <img {...imgAttrs(m, { sizes: '(min-width: 768px) 50vw, 100vw' })} />.
Add mediaAdminResource to src/genpm/admin.ts.
Verify: upload a photo with GPS data; after confirm, the stored file has no EXIF and the row has width/height.

Conventions

Reference media by id in content; resolve URLs at render time (driver or CDN can change).
Every non-decorative image needs alt; the admin can filter missingAlt=true.
Hero/LCP images: imgAttrs(m, { priority: true }); everything else stays lazy.

Don't

Don't accept files without confirmUpload; pending or rejected media must never be shown.
Don't presign uploads to the final public/ key: a signed PUT can be replayed until it expires and would swap a validated file for an unchecked one (served immutable). Upload to stagingKey(); only confirmUpload writes public/.
Don't allow SVG uploads or serve user files from the site's own origin without the storage route's sandbox headers.
Don't hotlink third-party images; copy them into storage first.

# @core/media — rules for AI agents

## Purpose
Media library on top of @core/storage: the browser uploads directly with a signed URL to a private staging key
(`uploads/pending/<id>.<ext>`), then `confirmUpload` checks the real file type by its bytes (declared type must match),
removes EXIF/GPS/XMP from JPEG, PNG and WebP without re-encoding, writes the validated bytes to the final `public/`
key, deletes the staging copy and stores dimensions. Malformed images (chunk lengths past the end) are rejected. Alt text and focal point per file, responsive URLs (Cloudflare Images or Next.js
image optimizer) and ready `<img>` attributes. SVG and HTML are never accepted. Table: `media`.

## Map
- `index.ts` — public API: `createUpload`, `confirmUpload`, `getMedia`, `updateMedia`, `deleteMedia`, `imageUrl`, `imgAttrs`, `mediaAdminResource`.
- `remote.ts` — `importRemoteImage(url, { allowedHosts })` for server-side imports (https, host allowlist, size limit).
- `library.ts` — upload flow, allowed types and `stagingKey(media)`. `sniff.ts`, `strip.ts` — byte checks. `urls.ts` — URLs and `<img>` attributes.
- `adapters/hono.ts` — `mediaRoutes({ authorize })`. `adapters/next.ts` — `createUploadRoute`, `confirmUploadRoute`.

## Integration
1. Configure @core/storage first (bucket CORS must allow `PUT` from the site). Recommended: a bucket lifecycle rule
   that deletes `uploads/pending/` objects after 1 day (abandoned or replayed uploads). Optional `MEDIA_TRANSFORM`:
   `cloudflare` (Images transformations enabled on the zone), `vercel` (Next.js image optimizer; add the storage host to `images.remotePatterns`) or `none`.
2. Migrations as in `src/lib/db/AGENTS.md`.
3. Mount the upload routes with an `authorize(req)` that returns `{ userId }` only for users with `media:create` (@core/rbac).
4. Upload from the browser: `POST /api/media/uploads` with `{ filename, mime, size }` → `PUT` the file to `upload.url`
   with `upload.headers` → `POST /api/media/uploads/<id>/confirm`. Store the media `id` in your content.
5. Render: `const m = await getMedia(id); <img {...imgAttrs(m, { sizes: '(min-width: 768px) 50vw, 100vw' })} />`.
6. Add `mediaAdminResource` to `src/genpm/admin.ts`.
7. Verify: upload a photo with GPS data; after confirm, the stored file has no EXIF and the row has width/height.

## Conventions
- Reference media by `id` in content; resolve URLs at render time (driver or CDN can change).
- Every non-decorative image needs `alt`; the admin can filter `missingAlt=true`.
- Hero/LCP images: `imgAttrs(m, { priority: true })`; everything else stays lazy.

## Don't
- Don't accept files without `confirmUpload`; pending or rejected media must never be shown.
- Don't presign uploads to the final `public/` key: a signed PUT can be replayed until it expires and would swap a
  validated file for an unchecked one (served `immutable`). Upload to `stagingKey()`; only `confirmUpload` writes `public/`.
- Don't allow SVG uploads or serve user files from the site's own origin without the storage route's sandbox headers.
- Don't hotlink third-party images; copy them into storage first.

Der genaue Baum, der nach .genpmignore eingebunden wird. Gepinnt an

src/lib/media/admin.tsschreibgeschützt · 868490c

// Recurso de panel "Medios": lista con filtros, edición de alt/punto focal/carpeta y borrado (también del archivo).
// La creación va por `createUpload` + `confirmUpload` (rutas en adapters/), no por el formulario genérico.
import { and, count, desc, eq, ilike, or, type SQL } from 'drizzle-orm';
import { z } from 'zod';
import type { AdminContext, AdminResource } from '../contracts/index.ts';
import { getDb } from '../db/index.ts';
import { deleteMedia, getMedia, MediaError, updateMedia } from './library.ts';
import { type Media, media } from './schema.ts';
import { mediaUrl } from './urls.ts';

async function need(ctx: AdminContext, action: string) {
  if (!(await ctx.can(`media:${action}`))) throw new MediaError('forbidden', `forbidden: media:${action}`);
}

const Patch = z.object({
  alt: z.string().max(500).optional(),
  filename: z.string().min(1).max(200).optional(),
  folder: z.string().max(170).optional(),
  focalX: z.coerce.number().min(0).max(1).optional(),
  focalY: z.coerce.number().min(0).max(1).optional(),
});

export const mediaAdminResource: AdminResource<Media> = {
  name: 'media',
  label: { singular: 'Media', plural: 'Media' },
  group: 'Content',
  fields: [
    { name: 'filename', label: 'File name', type: 'text', list: true },
    { name: 'alt', label: 'Alt text', type: 'textarea', help: 'Describe the image for people who cannot see it. Leave empty only if decorative.' },
    { name: 'folder', label: 'Folder', type: 'text', list: true },
    { name: 'mime', label: 'Type', type: 'text', readOnly: true, list: true },
    { name: 'size', label: 'Size (bytes)', type: 'number', readOnly: true },
    { name: 'focalX', label: 'Focal point X (0–1)', type: 'number' },
    { name: 'focalY', label: 'Focal point Y (0–1)', type: 'number' },
  ],
  input: Patch,
  title: (m) => m.filename,
  links: (m) => [{ label: 'Open file', href: mediaUrl(m) }],
  async list(q, ctx) {
    await need(ctx, 'read');
    const conds: SQL[] = [eq(media.status, 'ready')];
    if (q.filters?.folder !== undefined) conds.push(eq(media.folder, q.filters.folder));
    if (q.filters?.type) conds.push(ilike(media.mime, `${q.filters.type.replace(/[%_\\]/g, '')}/%`));
    if (q.filters?.missingAlt === 'true') conds.push(eq(media.alt, ''));
    if (q.search) conds.push(or(ilike(media.filename, `%${q.search.replace(/[%_\\]/g, (m) => `\\${m}`)}%`), ilike(media.alt, `%${q.search.replace(/[%_\\]/g, (m) => `\\${m}`)}%`))!);
    const where = and(...conds);
    const [total] = await getDb().select({ n: count() }).from(media).where(where);
    const rows = await getDb().select().from(media).where(where).orderBy(desc(media.createdAt), desc(media.id)).limit(q.pageSize).offset((Math.max(q.page, 1) - 1) * q.pageSize);
    return { rows, total: total?.n ?? 0 };
  },
  async get(id, ctx) {
    await need(ctx, 'read');
    return getMedia(id);
  },
  async update(id, input, ctx) {
    await need(ctx, 'update');
    return updateMedia(id, Patch.parse(input));
  },
  async delete(id, ctx) {
    await need(ctx, 'delete');
    await deleteMedia(id);
  },
};