ADR 0010 — Media path: presigned URLs from ddx-api after the org check

Superseded by ADR 0011 (2026-10-23, owner decision): MinIO is reached only by ddx-api; no presigned URL reaches a client. Kept as history.

• Status: Superseded by ADR 0011 (was Accepted 2026-10-23)
• Binds: WS4 G4.1-G4.3, WS4 NOT (no public bucket, no media without an org check, no CDN), invariants 1, 2, 3
• Research: RQ8 · confirms the S3 client of ADR 0005 (@aws-sdk/client-s3 + @aws-sdk/s3-request-presigner)

Context

ddx-web needs avatars, project cover images, audio and documents. MinIO runs locally with two private buckets (ddx-images, ddx-avatars). Bytes could go through the BFF and ddx-api, or straight to MinIO. Every object belongs to one org, and isolation must be testable.

Decision

1. Presigned URLs. ddx-api mints a presigned PUT (upload) or GET (read) URL. The bytes go between the browser and MinIO. The BFF forwards only the JSON calls.
2. Org check first. Every call runs the guard chain, then :orgSlug = principal org (OrgContextInterceptor), then the service. A URL is minted only after that. A media id of another org reads as absent (TenantPrismaService) → 404, no URL.
3. Keys carry the org. org/<orgId>/<kind>/<mediaId>; avatars org/<orgId>/avatars/<userId>/<mediaId>. ddx-api builds the key from the bound org (and the caller's user for avatars) on every call. A client never sends a key.
4. Short TTL, private buckets. MEDIA_PRESIGN_TTL_SECONDS (default 300, range 30-900). No public bucket policy, no permanent URL, no CDN. A presigned URL is a bearer credential: never logged, never stored.
5. Two-step upload. POST /orgs/:orgSlug/media/presign → client PUT → POST /orgs/:orgSlug/media/:id/complete. complete HEADs the object, re-checks size cap and content type (bad upload → deleted, 400), writes main.MediaObject, then links it: avatar → better-auth user.image = key; image with a project link → project.coverImageKey = key (through ProjectsService, so the entity.updated event goes on the one EVENTS_BUS).
6. Read. GET /orgs/:orgSlug/media/:id/url → presigned GET. The media id is the last key segment, so a stored key names its media id (mediaIdFromKey, @ddx/contracts/media).
7. Buckets. avatar → ddx-avatars; image, audio, document → ddx-images.
8. Config. S3_ENDPOINT, S3_PUBLIC_ENDPOINT (the host signed into the URL), S3_REGION, MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, S3_BUCKET_IMAGES, S3_BUCKET_AVATARS. A missing key fails the boot (no silent fallback).

Consequences

• No raised body limit on any ddx-api route for media (two-tier limit stays intact).
• The browser talks to MinIO on 127.0.0.1:16350 with a signed URL. This does not break invariant 1: the browser still never calls ddx-api directly. The ddx-docker-minio compose comment "the browser never reaches MinIO" needs an update by its owner.
• MinIO CORS must allow the ddx-web origin for browser PUT (default MinIO allows all); verified by the first ddx-web upload.
• An upload that is never completed leaves an orphan object. Cleanup (a lifecycle rule on org/* objects with no MediaObject row) is open work, not done here.
• Dev uses the MinIO root credentials. A non-dev target needs a scoped MinIO user with access to the two buckets only.
• Replacing an avatar does not delete the old object (open work, same as orphan cleanup).

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot