jskelet 0.6.10 → 0.6.12

package/CHANGELOG.md

@@ -16,11 +16,14 @@ one is listed under a **Breaking** heading.
   Production `jskelet build` PutObjects `public/assets/` (and optional
   `include` dirs) after precompress. Only credentials are read from env
   (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`, then
-  `JSKELET_S3_*`). The Assets upload step always appears on production builds;
-  when off it logs a one-line reason (`skipped (no build.assets.upload.bucket)`,
-  `skipped (credentials missing)`, …). A URL in `upload.bucket` is rejected
-  with a warning (CDN origin belongs in `prefix`). Watch mode never uploads.
-  `.br` / `.gz` siblings are skipped.
+  `JSKELET_S3_*`, then ECS task-role / EC2 instance-profile metadata). The
+  Assets upload step always appears on production builds; when off it logs a
+  one-line reason (`skipped (no build.assets.upload.bucket)`,
+  `skipped (credentials missing (no env keys, no ECS task role …))`, …).
+  Docker/`RUN jskelet build` has no task role — upload needs CI role or a
+  runtime upload. A URL in `upload.bucket` is rejected with a warning (CDN
+  origin belongs in `prefix`). Watch mode never uploads. `.br` / `.gz`
+  siblings are skipped.
 
 ### Changed
 

package/docs/07-yapilandirma.md

@@ -638,13 +638,13 @@ değişmez** — asset'ler origin'den servis edilir.
 | `assets.upload.include` | `string[]` | `["assets"]` | `public/` altı dizinler (`assets`, isteğe `fonts`, …). |
 | `assets.upload.cacheControl` | `string` | `public, max-age=31536000, immutable` | PutObject `Cache-Control`. |
 
-**Yalnızca credential env'den gelir:** `AWS_ACCESS_KEY_ID` /
-`AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` (yoksa `JSKELET_S3_*`). Prefix,
-bucket, region vb. config'te yazılır. Production build'de Assets upload adımı
-her zaman görünür; kapalıysa `skipped (no build.assets.upload.bucket)` /
-`skipped (credentials missing)` gibi tek satır sebep basılır. Watch'ta adım
-yok. `.br` / `.gz` yüklenmez. Ayrıntı: [08-build.md](./08-build.md),
-[10-dagitim.md](./10-dagitim.md).
+**Credential config'e yazılmaz.** Zincir: `AWS_ACCESS_KEY_ID` /
+`AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` (yoksa `JSKELET_S3_*`) → ECS/Fargate
+task role (`AWS_CONTAINER_CREDENTIALS_*`) → EC2 instance profile (IMDSv2).
+Prefix, bucket, region vb. config'te yazılır. Task role varken env key şart
+değil. Production build'de Assets upload adımı her zaman görünür; kapalıysa
+`skipped (…)` ile sebep basılır. Watch'ta adım yok. `.br` / `.gz` yüklenmez.
+Ayrıntı: [08-build.md](./08-build.md), [10-dagitim.md](./10-dagitim.md).
 
 ```js
 build: {

package/docs/08-build.md

@@ -84,8 +84,8 @@ dosya adlarını okunur tutuyor. Hash'li olmaları sayesinde bu dosyalara
 
 ### CDN prefix ve S3 upload
 
-Varsayılan kapalıdır. Prefix / bucket / keyPrefix config'te; yalnızca
-credential env'den (`AWS_*`, yoksa `JSKELET_S3_*`). Açılınca:
+Varsayılan kapalıdır. Prefix / bucket / keyPrefix config'te; credential
+env → ECS task role → EC2 IMDS zincirinden. Açılınca:
 
 1. Production build `public/assets/` (ve `include` listesindeki diğer dizinler)
    altındaki dosyaları S3'e PutObject ile kopyalar.

package/docs/10-dagitim.md

@@ -55,34 +55,41 @@ ayarlamayı düşünmeniz gerekenler:
 
 ### Asset'leri S3 / CloudFront'a basmak
 
-Varsayılan kapalıdır. Config'te prefix + bucket; CI'da yalnızca credential:
+Varsayılan kapalıdır. Config'te prefix + bucket; credential env key **veya**
+IAM role:
 
 ```js
-// jskelet.config.mjs
+// jskelet.config.mjs — uygulama env'lerini buraya bağla
 build: {
   assets: {
-    prefix: "https://static.ornek.com/js",
+    prefix: process.env.NEXT_PUBLIC_STATIC_ASSETS_BASE_URL, // https://static.…
     upload: {
-      bucket: "static.ornek.com", // veya "static.ornek.com/js"
+      bucket: process.env.S3_BUCKET_NAME, // static.investvio.com
       keyPrefix: "js",
-      region: "eu-central-1",
+      region: process.env.AWS_REGION || "eu-central-1",
+      endpoint: process.env.AWS_S3_ENDPOINT || undefined,
     },
   },
 },
 ```
 
-```bash
-AWS_ACCESS_KEY_ID=…
-AWS_SECRET_ACCESS_KEY=…
-# geçici credential ise:
-# AWS_SESSION_TOKEN=…
-```
+**Task role ne zaman çalışır?** ECS task role /
+`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` yalnızca **görev çalışırken** vardır.
+Dockerfile içindeki `RUN jskelet build` veya CI build agent'ında bu URI
+yoktur → `skipped (credentials missing (no env keys, no ECS task role …))`.
+AWS SDK'nın runtime'da rolü görmesi, build adımının rolü görmesi demek değildir.
+
+Pratik seçenekler:
+
+1. **CI'da rol ile build** (CodeBuild / GitHub OIDC) — static key yok, upload
+   build job'unda biter.
+2. **Image'da yalnızca derle**, upload'u ECS start'ta ayrı koş (task role o an
+   vardır).
+3. CI'da geçici `AWS_*` key (tercih edilmez).
 
-`jskelet build` bitince `public/assets/` (ve config'te `include` edilen
-dizinler) S3'e kopyalanır; origin'deki dosyalar da durur. Bucket veya
-credential yoksa adım `skipped (…)` ile sebep basar, build devam eder. Watch /
-`jskelet dev` upload yapmaz. CSP kullanıyorsanız CDN origin'ini `script-src` /
-`style-src` / `img-src` ve `preconnect` listesine ekleyin.
+`jskelet build` bitince `public/assets/` S3'e kopyalanır; origin kopyası durur.
+Bucket/credential yoksa adım `skipped (…)` basar. Watch / `jskelet dev` upload
+yapmaz. CSP'ye CDN origin ekleyin.
 
 Production'da dosya veya S3 sink açıldığında HTTP access log middleware
 otomatik mount edilir (`logs.kinds` içinde `http` varsa). Admin paneli ring'i

package/docs/en/07-configuration.md

@@ -651,13 +651,14 @@ changes** — assets stay on the origin.
 | `assets.upload.include` | `string[]` | `["assets"]` | Directories under `public/` (`assets`, optionally `fonts`, …). |
 | `assets.upload.cacheControl` | `string` | `public, max-age=31536000, immutable` | PutObject `Cache-Control`. |
 
-**Only credentials come from the environment:** `AWS_ACCESS_KEY_ID` /
-`AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` (else `JSKELET_S3_*`). Prefix,
-bucket, region, etc. are written in the config. On a production build the Assets
-upload step always appears; when off it logs a one-line reason such as
-`skipped (no build.assets.upload.bucket)` or `skipped (credentials missing)`.
-No upload on watch passes. `.br` / `.gz` siblings are not uploaded. Details:
-[08-build.md](./08-build.md), [10-deployment.md](./10-deployment.md).
+**Credentials are not written in the config.** Chain: `AWS_ACCESS_KEY_ID` /
+`AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` (else `JSKELET_S3_*`) → ECS/Fargate
+task role (`AWS_CONTAINER_CREDENTIALS_*`) → EC2 instance profile (IMDSv2).
+Prefix, bucket, region, etc. live in the config. With a task role, env keys are
+not required. On a production build the Assets upload step always appears; when
+off it logs `skipped (…)`. No upload on watch passes. `.br` / `.gz` siblings are
+not uploaded. Details: [08-build.md](./08-build.md),
+[10-deployment.md](./10-deployment.md).
 
 ```js
 build: {

package/docs/en/08-build.md

@@ -87,8 +87,8 @@ They are passed to templates automatically; in server code,
 
 ### CDN prefix and S3 upload
 
-Off by default. Prefix / bucket / keyPrefix come from config; only credentials
-come from the environment (`AWS_*`, else `JSKELET_S3_*`). When enabled:
+Off by default. Prefix / bucket / keyPrefix come from config; credentials
+resolve from env → ECS task role → EC2 IMDS. When enabled:
 
 1. A production build PutObjects files under `public/assets/` (and any other
    directories in `include`) to S3.

package/docs/en/10-deployment.md

@@ -56,34 +56,40 @@ considering in production:
 
 ### Publishing assets to S3 / CloudFront
 
-Off by default. Prefix + bucket in config; credentials only in CI:
+Off by default. Prefix + bucket in config; credentials from env keys **or** an
+IAM role:
 
 ```js
-// jskelet.config.mjs
+// jskelet.config.mjs — wire your app env vars here
 build: {
   assets: {
-    prefix: "https://static.example.com/js",
+    prefix: process.env.NEXT_PUBLIC_STATIC_ASSETS_BASE_URL, // https://static.…
     upload: {
-      bucket: "static.example.com", // or "static.example.com/js"
+      bucket: process.env.S3_BUCKET_NAME, // static.example.com
       keyPrefix: "js",
-      region: "eu-central-1",
+      region: process.env.AWS_REGION || "eu-central-1",
+      endpoint: process.env.AWS_S3_ENDPOINT || undefined,
     },
   },
 },
 ```
 
-```bash
-AWS_ACCESS_KEY_ID=…
-AWS_SECRET_ACCESS_KEY=…
-# for temporary credentials:
-# AWS_SESSION_TOKEN=…
-```
+**When does the task role work?** The ECS task role /
+`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` exist only while the **task is
+running**. A `RUN jskelet build` inside Docker or a CI build agent has no such
+URI → `skipped (credentials missing (no env keys, no ECS task role …))`. The AWS
+SDK seeing the role at runtime does not mean the build step sees it.
+
+Practical options:
+
+1. **Build with a CI role** (CodeBuild / GitHub OIDC) — no static keys; upload
+   finishes in the job.
+2. **Compile in the image**, run upload at ECS start (task role is present then).
+3. Temporary `AWS_*` keys in CI (not preferred).
 
-When `jskelet build` finishes, files under `public/assets/` (and any other
-`include` directories) are copied to S3; origin copies remain. If the bucket or
-credentials are missing, the step logs `skipped (…)` with the reason and the
-build continues. Watch / `jskelet dev` never upload. If you use CSP, add the CDN
-origin to `script-src` / `style-src` / `img-src` and to `preconnect`.
+When `jskelet build` finishes, `public/assets/` is copied to S3; origin copies
+remain. Missing bucket/credentials log `skipped (…)`. Watch / `jskelet dev`
+never upload. Add the CDN origin to CSP.
 
 When a file or S3 sink is enabled in production, the HTTP access log middleware
 mounts automatically (if `http` is in `logs.kinds`). The admin panel ring is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk SSR (optional EJS peer), vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/build/tasks/assets-upload.mjs

@@ -1,16 +1,21 @@
 /**
  * Production build sonunda hash'li varlıkları S3'e PutObject ile kopyalar.
  *
- * Watch turunda çalışmaz (çağıran sorumlu). Credential env'den gelir
- * (`AWS_*` önce, `JSKELET_S3_*` yedek). Bucket / credential yoksa veya upload
- * kapalıysa adım yine görünür: `skipped (…)` ile sebep basılır, build düşmez.
+ * Watch turunda çalışmaz (çağıran sorumlu). Credential: env (`AWS_*` /
+ * `JSKELET_S3_*`) → ECS task role → EC2 instance profile. Bucket yoksa veya
+ * upload kapalıysa adım yine görünür: `skipped (…)` ile sebep basılır.
+ * Credential yalnızca env+metadata zinciri boşsa skip; task role varken
+ * env key şart değil.
  *
  * `.br` / `.gz` kardeşleri yüklenmez: edge kendi sıkıştırmasını yapsın;
  * origin precompress Express için kalır.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { readS3CredentialsFromEnv } from "../../config/index.js";
+import {
+  resolveS3Credentials,
+  s3CredentialsMissingReason,
+} from "../../server/logs/s3-credentials.js";
 import { putObject } from "../../server/logs/s3-put.js";
 import * as log from "../../log.mjs";
 import { paths } from "../paths.mjs";
@@ -88,7 +93,7 @@ function resolveIncludeDir(name) {
 }
 
 /**
- * Upload yapılmayacaksa kısa sebep; yapılacaksa `null`.
+ * Config kapısı — credential burada bakılmaz (task role async).
  *
  * @param {import('../../config/index.js').ResolvedConfig} config
  * @returns {string | null}
@@ -105,14 +110,13 @@ export function assetsUploadSkipReason(config) {
 
   if (!upload.bucket) return "no build.assets.upload.bucket";
 
-  if (!readS3CredentialsFromEnv()) return "credentials missing";
-
   return null;
 }
 
 /**
  * @param {import('../../config/index.js').ResolvedConfig} config
- * @param {{ put?: typeof putObject }} [options]
+ * @param {{ put?: typeof putObject,
+ *   resolveCredentials?: typeof resolveS3Credentials }} [options]
  * @returns {Promise<void>}
  */
 export async function uploadAssets(config, options = {}) {
@@ -123,15 +127,17 @@ export async function uploadAssets(config, options = {}) {
   }
 
   const upload = config.build.assets.upload;
-  const credentials = readS3CredentialsFromEnv();
-  // skipReason null iken credential ve bucket vardır; TS/akış için daralt.
+  const resolve = options.resolveCredentials ?? resolveS3Credentials;
+  const credentials = await resolve();
   if (!upload.bucket || !credentials) {
-    log.detail("skipped (credentials missing)");
+    log.detail(`skipped (${s3CredentialsMissingReason()})`);
     return;
   }
 
   const put = options.put ?? putObject;
-  const keyPrefix = (upload.keyPrefix || "").replace(/^\/+/, "");
+  // Normalize bazen atlanır (test / elle config); önek `/` ile bitsin.
+  let keyPrefix = (upload.keyPrefix || "").replace(/^\/+/, "");
+  if (keyPrefix && !keyPrefix.endsWith("/")) keyPrefix += "/";
 
   /** @type {{ file: string, key: string }[]} */
   const jobs = [];

package/src/config/index.js

@@ -33,6 +33,10 @@ import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
 import { compilePattern, matchPattern } from "./pattern.js";
+import {
+  readS3CredentialsFromEnv,
+  resolveS3Credentials,
+} from "../server/logs/s3-credentials.js";
 import {
   DEFAULT_ADMIN,
   DEFAULT_AUTH,
@@ -64,6 +68,8 @@ import {
   DEFAULT_UPSTREAM_LIMIT,
 } from "./defaults.js";
 
+export { readS3CredentialsFromEnv, resolveS3Credentials };
+
 /** Framework paketinin kökü — kendi şablonlarına ve varlıklarına erişir. */
 export const FRAMEWORK_ROOT = path.resolve(import.meta.dirname, "..", "..");
 
@@ -527,32 +533,6 @@ function envText(value) {
   return typeof value === "string" && value ? value : null;
 }
 
-/**
- * S3 imza credential'ları. AWS deploy'da standart env önce gelir; R2/MinIO
- * için `JSKELET_S3_*` yedek. IAM instance/task role (IMDS) desteklenmez —
- * CI'da `configure-aws-credentials` gibi araçlar zaten `AWS_*` basar.
- *
- * @returns {{ accessKeyId: string, secretAccessKey: string,
- *   sessionToken: string | null } | null}
- */
-export function readS3CredentialsFromEnv() {
-  const accessKeyId =
-    envText(process.env.AWS_ACCESS_KEY_ID) ??
-    envText(process.env.JSKELET_S3_ACCESS_KEY_ID);
-  const secretAccessKey =
-    envText(process.env.AWS_SECRET_ACCESS_KEY) ??
-    envText(process.env.JSKELET_S3_SECRET_ACCESS_KEY) ??
-    envText(process.env.JSKELET_S3_ACCESS_SECRET);
-  if (!accessKeyId || !secretAccessKey) return null;
-  return {
-    accessKeyId,
-    secretAccessKey,
-    sessionToken:
-      envText(process.env.AWS_SESSION_TOKEN) ??
-      envText(process.env.JSKELET_S3_SESSION_TOKEN),
-  };
-}
-
 /**
  * Log hedefi. Öncelik: `JSKELET_LOG_BUCKET` → `JSKELET_S3_BUCKET`
  * (+ isteğe bağlı `JSKELET_S3_KEY_PREFIX`).

package/src/server/logs/pipeline.js

@@ -6,9 +6,9 @@
  */
 import process from "node:process";
 import * as log from "../../log.mjs";
-import { readS3CredentialsFromEnv } from "../../config/index.js";
 import { createFileSink } from "./file-sink.js";
 import { createS3Sink } from "./s3-sink.js";
+import { resolveS3Credentials } from "./s3-credentials.js";
 
 /**
  * @typedef {import('../../config/index.js').LogsConfig} LogsConfig
@@ -73,14 +73,15 @@ export async function configureLogs(config) {
   }
 
   if (logs.s3.enabled) {
-    const credentials = readS3CredentialsFromEnv();
+    const credentials = await resolveS3Credentials();
     if (!logs.s3.bucket) {
       console.warn(
         "[logs] s3.enabled but no bucket (set JSKELET_LOG_BUCKET, JSKELET_S3_BUCKET or logs.s3.bucket)",
       );
     } else if (!credentials) {
       console.warn(
-        "[logs] s3.enabled but credentials missing — set AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or JSKELET_S3_*",
+        "[logs] s3.enabled but credentials missing — set AWS_ACCESS_KEY_ID/" +
+          "AWS_SECRET_ACCESS_KEY or JSKELET_S3_*, or run with an ECS/EC2 IAM role",
       );
     } else {
       const region = logs.s3.region || "auto";

package/src/server/logs/s3-credentials.js

@@ -0,0 +1,212 @@
+/**
+ * S3 imza credential zinciri — SDK yok.
+ *
+ * 1. Env: `AWS_*` sonra `JSKELET_S3_*`
+ * 2. ECS/Fargate task role: `AWS_CONTAINER_CREDENTIALS_*`
+ * 3. EC2 instance profile: IMDSv2 (kısa timeout; local'de asılı kalmaz)
+ *
+ * EKS IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`) bilinçli olarak yok — STS çağrısı
+ * ayrı yüzey; CI genelde zaten `AWS_*` basar.
+ */
+import fs from "node:fs";
+import process from "node:process";
+
+/**
+ * @typedef {{ accessKeyId: string, secretAccessKey: string,
+ *   sessionToken: string | null }} AwsCredentials
+ */
+
+// Local'de IMDS yokken hızlı vazgeç; ECS'te URI varken biraz daha sabır.
+const IMDS_TIMEOUT_MS = 400;
+const ECS_TIMEOUT_MS = 2_000;
+const ECS_METADATA_HOST = "http://169.254.170.2";
+const EC2_METADATA_HOST = "http://169.254.169.254";
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function envText(value) {
+  return typeof value === "string" && value ? value : null;
+}
+
+/**
+ * @returns {AwsCredentials | null}
+ */
+export function readS3CredentialsFromEnv() {
+  const accessKeyId =
+    envText(process.env.AWS_ACCESS_KEY_ID) ??
+    envText(process.env.JSKELET_S3_ACCESS_KEY_ID);
+  const secretAccessKey =
+    envText(process.env.AWS_SECRET_ACCESS_KEY) ??
+    envText(process.env.JSKELET_S3_SECRET_ACCESS_KEY) ??
+    envText(process.env.JSKELET_S3_ACCESS_SECRET);
+  if (!accessKeyId || !secretAccessKey) return null;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    sessionToken:
+      envText(process.env.AWS_SESSION_TOKEN) ??
+      envText(process.env.JSKELET_S3_SESSION_TOKEN),
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} data
+ * @returns {AwsCredentials | null}
+ */
+function fromAwsCredentialJson(data) {
+  const accessKeyId =
+    typeof data.AccessKeyId === "string" ? data.AccessKeyId : null;
+  const secretAccessKey =
+    typeof data.SecretAccessKey === "string" ? data.SecretAccessKey : null;
+  if (!accessKeyId || !secretAccessKey) return null;
+  const token =
+    (typeof data.Token === "string" && data.Token) ||
+    (typeof data.SessionToken === "string" && data.SessionToken) ||
+    null;
+  return { accessKeyId, secretAccessKey, sessionToken: token };
+}
+
+/**
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {number} [timeoutMs]
+ * @returns {Promise<unknown | null>}
+ */
+async function fetchJson(url, init = {}, timeoutMs = IMDS_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string | null>}
+ */
+async function fetchText(url, init = {}, timeoutMs = IMDS_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    if (!response.ok) return null;
+    return (await response.text()).trim() || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * ECS task role / container credential provider.
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export async function readS3CredentialsFromEcs() {
+  const relative = envText(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI);
+  const full = envText(process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI);
+  if (!relative && !full) return null;
+
+  const url = full ?? `${ECS_METADATA_HOST}${relative}`;
+
+  /** @type {Record<string, string>} */
+  const headers = {};
+  const token =
+    envText(process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN) ??
+    readTokenFile(process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE);
+  if (token) headers.Authorization = token;
+
+  const data = await fetchJson(url, { headers }, ECS_TIMEOUT_MS);
+  if (!data || typeof data !== "object") return null;
+  return fromAwsCredentialJson(/** @type {Record<string, unknown>} */ (data));
+}
+
+/**
+ * @param {unknown} pathValue
+ * @returns {string | null}
+ */
+function readTokenFile(pathValue) {
+  const file = envText(pathValue);
+  if (!file) return null;
+  try {
+    const text = fs.readFileSync(file, "utf8").trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * EC2 instance profile via IMDSv2 (IMDSv1'e düşmez).
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export async function readS3CredentialsFromImds() {
+  const token = await fetchText(
+    `${EC2_METADATA_HOST}/latest/api/token`,
+    {
+      method: "PUT",
+      headers: { "X-aws-ec2-metadata-token-ttl-seconds": "21600" },
+    },
+  );
+  if (!token) return null;
+
+  const headers = { "X-aws-ec2-metadata-token": token };
+  const roleName = await fetchText(
+    `${EC2_METADATA_HOST}/latest/meta-data/iam/security-credentials/`,
+    { headers },
+  );
+  if (!roleName) return null;
+
+  // Birden fazla satır olursa ilki.
+  const role = roleName.split("\n")[0]?.trim();
+  if (!role || role.includes("..") || role.includes("/")) return null;
+
+  const data = await fetchJson(
+    `${EC2_METADATA_HOST}/latest/meta-data/iam/security-credentials/${encodeURIComponent(role)}`,
+    { headers },
+  );
+  if (!data || typeof data !== "object") return null;
+  return fromAwsCredentialJson(/** @type {Record<string, unknown>} */ (data));
+}
+
+/**
+ * Credential neden bulunamadı — upload skip satırı için.
+ *
+ * @returns {string}
+ */
+export function s3CredentialsMissingReason() {
+  if (
+    envText(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI) ||
+    envText(process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI)
+  ) {
+    return "credentials missing (ECS metadata failed)";
+  }
+  return "credentials missing (no env keys, no ECS task role — upload needs runtime/CI role, not docker build)";
+}
+
+/**
+ * Env → ECS task role → EC2 instance profile.
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export async function resolveS3Credentials() {
+  const fromEnv = readS3CredentialsFromEnv();
+  if (fromEnv) return fromEnv;
+
+  const fromEcs = await readS3CredentialsFromEcs();
+  if (fromEcs) return fromEcs;
+
+  return readS3CredentialsFromImds();
+}

package/src/server/logs/s3-put.js

@@ -2,9 +2,8 @@
  * Minimal S3 PutObject — yalnızca SigV4 + `fetch`.
  *
  * `@aws-sdk/client-s3` taşınmıyor: tek operasyon için SDK'nın maliyeti ve
- * peer yüzeyi gereksiz. Credential zinciri env'den okunur (`AWS_*` önce,
- * sonra `JSKELET_S3_*`); IAM role / instance metadata yok — CI'da
- * `configure-aws-credentials` gibi araçlar key basar.
+ * peer yüzeyi gereksiz. Credential `resolveS3Credentials` ile gelir
+ * (env → ECS task role → EC2 IMDS).
  */
 import crypto from "node:crypto";
 

package/types/config/index.d.ts

@@ -1,4 +1,6 @@
+import { readS3CredentialsFromEnv, resolveS3Credentials } from "../server/logs/s3-credentials.js";
 import { DEFAULT_ADMIN, DEFAULT_CLOUDFLARE, DEFAULT_UPSTREAM_LIMIT } from "./defaults.js";
+export { readS3CredentialsFromEnv, resolveS3Credentials };
 /** Framework paketinin kökü — kendi şablonlarına ve varlıklarına erişir. */
 export declare const FRAMEWORK_ROOT: string;
 export type Eagerness = "conservative" | "moderate" | "eager";
@@ -278,19 +280,6 @@ export declare function splitS3BucketPath(value: string | null): {
     bucket: string | null;
     prefix: string | null;
 };
-/**
- * S3 imza credential'ları. AWS deploy'da standart env önce gelir; R2/MinIO
- * için `JSKELET_S3_*` yedek. IAM instance/task role (IMDS) desteklenmez —
- * CI'da `configure-aws-credentials` gibi araçlar zaten `AWS_*` basar.
- *
- * @returns {{ accessKeyId: string, secretAccessKey: string,
- *   sessionToken: string | null } | null}
- */
-export declare function readS3CredentialsFromEnv(): {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken: string | null;
-} | null;
 /**
  * Kalıcı log sink'leri. Bozuk bir `kinds` listesi siteyi düşürmemeli —
  * bilinmeyen girdiler atılır; hiç geçerli tür kalmazsa varsayılana dönülür.

package/types/server/logs/s3-credentials.d.ts

@@ -0,0 +1,33 @@
+export type AwsCredentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string | null;
+};
+/**
+ * @returns {AwsCredentials | null}
+ */
+export declare function readS3CredentialsFromEnv(): AwsCredentials | null;
+/**
+ * ECS task role / container credential provider.
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export declare function readS3CredentialsFromEcs(): Promise<AwsCredentials | null>;
+/**
+ * EC2 instance profile via IMDSv2 (IMDSv1'e düşmez).
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export declare function readS3CredentialsFromImds(): Promise<AwsCredentials | null>;
+/**
+ * Credential neden bulunamadı — upload skip satırı için.
+ *
+ * @returns {string}
+ */
+export declare function s3CredentialsMissingReason(): string;
+/**
+ * Env → ECS task role → EC2 instance profile.
+ *
+ * @returns {Promise<AwsCredentials | null>}
+ */
+export declare function resolveS3Credentials(): Promise<AwsCredentials | null>;