@ailuntz/resource-agent 1.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @ailuntz/resource-agent
+
+Authenticated short-lived S3 download links, with health-aware Cloudflare Tunnel selection and elastic connector workers. Clients receive one link; object data travels through the selected tunnel, without passing through the application backend.
+
+```sh
+npm install @ailuntz/resource-agent@1.1.0
+```
+
+Backend integration:
+
+```js
+import { signedRequest } from '@ailuntz/resource-agent/client';
+const request = await signedRequest({
+  clientId: 'shop', secret: process.env.DOWNLOAD_CLIENT_SECRET,
+  path: '/v1/downloads',
+  body: { bucket: 'shop-files', key: 'resources/example.zip',
+    filename: 'example.zip', expiresAt: Date.now() + 120000 },
+});
+const result = await fetch(process.env.DOWNLOAD_AGENT_URL + '/v1/downloads', request);
+```
+
+Authenticate the user and check resource access on your backend **before** making this request. Never distribute the client secret or storage signing key to browsers.
+
+## Runtime
+
+Run `ailuntz-downloads serve --runtime /runtime` and `ailuntz-downloads channels --runtime /runtime` as separate supervised services. There is no native service installer.
+
+- `secrets/agent.json`: S3 read-only signing credentials and per-client shared secrets/bucket allowlists.
+- `channels.json`: four pre-provisioned tunnel definitions; first channel id `primary`.
+- `channel-policy.json`: minimum/maximum channels, scaling and draining intervals.
+- `state/`: shared writable health snapshots and admission markers.
+- `AILUNTZ_CONFIG_DIR`: optional directory holding channel definitions/policy.
+- `CLOUDFLARED_BIN`: path to a pinned cloudflared executable. In containers, `AILUNTZ_CONTAINER=1` sends worker output to container logs.
+
+The primary tunnel and control tunnel run separately. The channel manager starts/stops additional cloudflared processes in its own container, without host process control or a Docker socket. Shared networking gives these workers access to the download gateway; shared state lets the gateway stop issuing new links before a lane drains.
+
+## HTTP API
+
+| Route | Purpose |
+|---|---|
+| `GET /healthz` | Liveness only |
+| `POST /v1/downloads` | Signed GET link; maximum 120 seconds, bounded by authorization expiry |
+| `POST /v1/objects/stat` | Authorized object size lookup |
+
+`serve` binds to loopback port 19081. Signatures bind the caller, method, path, timestamp, nonce and body. Nonces cannot be reused within the process. Requests with a browser Origin, disallowed bucket, invalid path or expired grant are rejected. Restarting clears replay memory; the original authorization deadline still applies.
+
+Scaling preserves existing transfers: stop issuing links, wait at least 150 seconds, and require zero observed in-flight requests before stopping a worker. Missing metrics never permit draining. New requests try healthy lanes after a failure; an interrupted download needs a new URL and a client that supports Range resumption. Multiple tunnels share the same physical uplink.
+
+The package contains code only: no deployment credentials, tunnel tokens, customer objects or production host configuration. The Docker image `ailuntz/download-agent:1.1.0` installs this exact npm release and a pinned official cloudflared binary.

package/bin/ailuntz-downloads.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const command = process.argv[2], index = process.argv.indexOf('--runtime');
+const runtime = path.resolve(index >= 0 ? process.argv[index + 1] : process.env.AILUNTZ_RUNTIME || path.join(os.homedir(), '.ailuntz-downloads'));
+process.env.AILUNTZ_RUNTIME = runtime;
+try {
+  if (command === 'serve') await (await import('../src/server.mjs')).serve(runtime);
+  else if (command === 'channels') await import('../src/channel-controller.mjs');
+  else if (command === 'status') {
+    const state = JSON.parse(fs.readFileSync(runtime + '/state/channels.json'));
+    const agent = JSON.parse(fs.readFileSync(runtime + '/state/agent.json'));
+    console.log(JSON.stringify({agent, policy: state.policy, checkedAt: state.checkedAt, channels: state.channels}, null, 2));
+    if (Date.now() - Date.parse(agent.checkedAt) > 15000 || Date.now() - Date.parse(state.checkedAt) > 15000) process.exitCode = 1;
+  } else console.log('ailuntz-downloads <serve|channels|status> [--runtime directory]');
+} catch {
+  console.error('Download service could not complete the operation; check local configuration and service status.');
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ailuntz/resource-agent",
+  "version": "1.1.0",
+  "description": "Authenticated S3 download links and elastic Cloudflare tunnel workers",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "ailuntz-downloads": "bin/ailuntz-downloads.mjs"
+  },
+  "exports": {
+    "./client": "./src/client.mjs",
+    "./policy": "./src/channel-policy.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "aws4fetch": "1.0.20"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/channel-controller.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';import os from 'node:os';import path from 'node:path';import {spawn} from 'node:child_process';
+import {validatePolicy,scalingDecision,safeToStop} from './channel-policy.mjs';
+const runtime=process.env.AILUNTZ_RUNTIME||path.join(os.homedir(),'Library/Application Support/AiluntzDownloads');
+const configRoot=process.env.AILUNTZ_CONFIG_DIR||runtime;
+const definitions=JSON.parse(fs.readFileSync(configRoot+'/channels.json'));
+if(definitions.length!==4||definitions[0].id!=='primary')throw Error('Invalid channel definitions');
+const readyRoot=runtime+'/state/ready';fs.mkdirSync(readyRoot,{recursive:true,mode:0o700});
+const channels=definitions.map(c=>({...c,state:c.id==='primary'?'starting':'stopped',healthy:false,requests:null,child:null,lastStart:0,drainStarted:null}));
+const marker=c=>readyRoot+'/'+c.hostname+'.ready';
+const remove=c=>fs.rmSync(marker(c),{force:true});
+for(const c of channels)remove(c);
+let policy=validatePolicy(JSON.parse(fs.readFileSync(configRoot+'/channel-policy.json'))),busySince=null,idleSince=null,stopping=false;
+function start(c){
+ if(c.id==='primary'||c.child)return;
+ remove(c);c.state='starting';c.lastStart=Date.now();c.drainStarted=null;
+ const container=process.env.AILUNTZ_CONTAINER==='1';
+ const fd=container?null:fs.openSync(runtime+'/logs/'+c.id+'.log','a',0o600);
+ c.child=spawn(process.env.CLOUDFLARED_BIN||runtime+'/bin/cloudflared',['tunnel','--no-autoupdate','--loglevel','error','--metrics','127.0.0.1:'+c.metricsPort,'--grace-period','3m','run','--token-file',runtime+'/secrets/'+c.tokenFile],{stdio:container?['ignore','inherit','inherit']:['ignore',fd,fd]});if(fd!==null)fs.closeSync(fd);
+ c.child.once('error',()=>{remove(c);c.healthy=false;});
+ c.child.once('close',()=>{c.child=null;c.healthy=false;c.requests=null;remove(c);if(c.state==='stopping')c.state='stopped';});
+}
+async function observe(c){
+ if(c.state==='stopped'||c.state==='stopping')return;
+ try{
+  const [health,metrics]=await Promise.all([
+   fetch('http://127.0.0.1:'+c.metricsPort+'/ready',{signal:AbortSignal.timeout(1500)}),
+   fetch('http://127.0.0.1:'+c.metricsPort+'/metrics',{signal:AbortSignal.timeout(1500)}),
+  ]);
+  const text=await metrics.text(),match=text.match(/^cloudflared_tunnel_concurrent_requests_per_tunnel(?:\{[^\n]*\})? ([\d.e+\-]+)$/m);
+  c.healthy=health.status===200;c.requests=match?Number(match[1]):null;
+  if(c.healthy&&c.state==='starting')c.state='ready';
+ }catch{c.healthy=false;c.requests=null;}
+ if(c.state==='ready'&&c.healthy){if(!fs.existsSync(marker(c)))fs.writeFileSync(marker(c),'ready\n',{mode:0o600});}
+ else remove(c);
+}
+async function tick(){
+ let policyError=false;
+ try{policy=validatePolicy(JSON.parse(fs.readFileSync(configRoot+'/channel-policy.json')));}catch{policyError=true;}
+ for(const c of channels){if(c.id!=='primary'&&['ready','starting','draining'].includes(c.state)&&!c.child&&Date.now()-c.lastStart>=15000){
+  // A crashed draining lane must stay withdrawn while its old links expire.
+  const oldState=c.state,oldDrain=c.drainStarted;start(c);if(oldState==='draining'){c.state=oldState;c.drainStarted=oldDrain;}
+ }}
+ await Promise.all(channels.map(observe));
+ const now=Date.now();
+ const decision=scalingDecision({policy,channels,now,busySince,idleSince});busySince=decision.busySince;idleSince=decision.idleSince;
+ if(decision.start&&!stopping)start(channels.find(c=>c.id===decision.start));
+ if(decision.resume&&!stopping){const c=channels.find(c=>c.id===decision.resume);c.state=c.healthy?'ready':'starting';c.drainStarted=null;}
+ if(decision.drain){const c=channels.find(c=>c.id===decision.drain);c.state='draining';c.drainStarted=now;remove(c);}
+ for(const c of channels){
+  if(safeToStop(c,now,policy)){c.state='stopping';remove(c);if(c.child)c.child.kill('SIGTERM');else c.state='stopped';}
+ }
+ const snapshot={checkedAt:new Date().toISOString(),policy,policyError,channels:channels.map(({id,hostname,state,healthy,requests,drainStarted})=>({id,hostname,state,healthy,requests,drainStarted}))};
+ const tmp=runtime+'/state/channels.json.tmp';fs.writeFileSync(tmp,JSON.stringify(snapshot,null,2)+'\n',{mode:0o600});fs.renameSync(tmp,runtime+'/state/channels.json');
+}
+async function shutdown(){
+ if(stopping)return;stopping=true;
+ // Maintenance must drain extras via policy first. On shutdown, cloudflared's
+ // own graceful exit keeps already-started requests alive as long as possible.
+ for(const c of channels){remove(c);if(c.child)c.child.kill('SIGTERM');}
+}
+process.on('SIGTERM',()=>void shutdown());process.on('SIGINT',()=>void shutdown());
+while(!stopping){try{await tick();}catch{console.error('Channel check failed; keeping existing transfers.');}await new Promise(r=>setTimeout(r,5000));}
+await Promise.all(channels.filter(c=>c.child).map(c=>new Promise(resolve=>c.child.once('close',resolve))));

package/src/channel-policy.mjs

@@ -0,0 +1,39 @@
+export function validatePolicy(p, count=4) {
+ const integer=(name,min,max)=>{if(!Number.isInteger(p[name])||p[name]<min||p[name]>max)throw Error('Invalid channel policy: '+name);};
+ integer('minChannels',1,count);integer('maxChannels',p.minChannels,count);
+ integer('requestsPerChannel',1,100);integer('scaleUpSeconds',15,600);integer('idleSeconds',60,86400);
+ // Issued URLs last at most 120 seconds; allow for in-flight authorization/probes.
+ integer('drainSeconds',150,3600);
+ if(typeof p.autoScale!=='boolean')throw Error('Invalid channel policy: autoScale');
+ return p;
+}
+export function scalingDecision({policy,channels,now,busySince,idleSince}) {
+ const accepting=channels.filter(c=>c.state==='ready'||c.state==='starting');
+ const draining=channels.filter(c=>c.state==='draining');
+ const running=channels.filter(c=>c.state!=='stopped');
+ const ready=channels.filter(c=>c.state==='ready'&&c.healthy);
+ const known=ready.length===accepting.length&&ready.every(c=>Number.isFinite(c.requests));
+ const requests=ready.reduce((sum,c)=>sum+(c.requests||0),0);
+ let busy=known&&requests>=ready.length*policy.requestsPerChannel&&ready.length>0;
+ let idle=known&&requests<=Math.max(0,ready.length-2);
+ busySince=busy?(busySince??now):null;idleSince=idle?(idleSince??now):null;
+ const result={busySince,idleSince};
+ // A changed cap immediately removes excess lanes from new-link allocation,
+ // but they remain alive until all issued links and transfers have drained.
+ if(accepting.length>policy.maxChannels){result.drain=accepting.filter(c=>c.id!=='primary').at(-1)?.id;return result;}
+ if(accepting.length<policy.minChannels){
+  if(draining.length)result.resume=draining[0].id;
+  else if(running.length<policy.maxChannels)result.start=channels.find(c=>c.state==='stopped')?.id;
+  return result;
+ }
+ if(draining.length||accepting.some(c=>c.state==='starting'))return result;
+ if(policy.autoScale&&busySince!==null&&now-busySince>=policy.scaleUpSeconds*1000&&running.length<policy.maxChannels){
+  result.start=channels.find(c=>c.state==='stopped')?.id;result.busySince=null;result.idleSince=null;
+ }else if(accepting.length>policy.minChannels&&(!policy.autoScale||(idleSince!==null&&now-idleSince>=policy.idleSeconds*1000))){
+  result.drain=[...ready].filter(c=>c.id!=='primary').sort((a,b)=>a.requests-b.requests)[0]?.id;result.idleSince=null;result.busySince=null;
+ }
+ return result;
+}
+export function safeToStop(channel, now, policy) {
+ return channel.state==='draining'&&Number.isFinite(channel.requests)&&channel.requests===0&&now-channel.drainStarted>=policy.drainSeconds*1000;
+}

package/src/client.mjs

@@ -0,0 +1,15 @@
+// This module uses Web APIs only, so the same protocol works in Node and Deno.
+const encoder = new TextEncoder();
+const hex = bytes => Array.from(new Uint8Array(bytes), x => x.toString(16).padStart(2, '0')).join('');
+export async function signedRequest({clientId, secret, path, body, now = Date.now(), nonce = crypto.randomUUID()}) {
+  const text = JSON.stringify(body), timestamp = String(Math.floor(now / 1000));
+  const digest = hex(await crypto.subtle.digest('SHA-256', encoder.encode(text)));
+  const message = ['download-agent-v1', clientId, 'POST', path, timestamp, nonce, digest].join('\n');
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), {name: 'HMAC', hash: 'SHA-256'}, false, ['sign']);
+  const signature = hex(await crypto.subtle.sign('HMAC', key, encoder.encode(message)));
+  return {method: 'POST', body: text, redirect: 'error', headers: {
+    'Content-Type': 'application/json',
+    'X-Download-Client': clientId, 'X-Download-Timestamp': timestamp,
+    'X-Download-Nonce': nonce, 'X-Download-Signature': signature,
+  }};
+}

package/src/server.mjs

@@ -0,0 +1,54 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import {createDownloadService} from './service.mjs';
+
+export async function serve(runtime) {
+  const config = JSON.parse(fs.readFileSync(runtime + '/secrets/agent.json'));
+  const channels = JSON.parse(fs.readFileSync((process.env.AILUNTZ_CONFIG_DIR || runtime) + '/channels.json'));
+  const service = createDownloadService({config, channels, snapshot: () => {
+    const state = JSON.parse(fs.readFileSync(runtime + '/state/channels.json'));
+    // Markers disappear at the start of draining, before the next snapshot.
+    state.channels = state.channels.filter(c => fs.existsSync(runtime + '/state/ready/' + c.hostname + '.ready'));
+    return state;
+  }});
+  const server = http.createServer({requestTimeout: 10000, headersTimeout: 5000, maxHeaderSize: 8192}, async (req, res) => {
+    try {
+      const chunks = []; let size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 8192) {
+          res.writeHead(413, {'Connection': 'close', 'Cache-Control': 'no-store'}); res.end(); return;
+        }
+        chunks.push(chunk);
+      }
+      const method = req.method || 'GET', body = Buffer.concat(chunks);
+      const input = new Request('http://127.0.0.1:19081' + req.url, {
+        method, headers: req.headers,
+        ...(!['GET', 'HEAD'].includes(method) ? {body} : {}),
+      });
+      const result = await service.handle(input);
+      res.writeHead(result.status, Object.fromEntries(result.headers));
+      res.end(Buffer.from(await result.arrayBuffer()));
+    } catch {
+      if (!res.headersSent) res.writeHead(400, {'Cache-Control': 'no-store'});
+      res.end();
+    }
+  });
+  server.maxHeadersCount = 40;
+  server.maxConnections = 64;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(19081, '127.0.0.1', resolve); });
+  const writeStatus = () => {
+    const data = {version: '1.1.0', pid: process.pid, checkedAt: new Date().toISOString(), ...service.status()};
+    const tmp = runtime + '/state/agent.json.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', {mode: 0o600});
+    fs.renameSync(tmp, runtime + '/state/agent.json');
+  };
+  writeStatus();
+  const timer = setInterval(writeStatus, 5000);
+  const stop = () => {
+    clearInterval(timer); server.close(() => process.exit(0));
+    setTimeout(() => { server.closeAllConnections(); process.exit(0); }, 12000).unref();
+  };
+  process.once('SIGTERM', stop); process.once('SIGINT', stop);
+  console.log('Download agent listening on loopback.');
+}

package/src/service.mjs

@@ -0,0 +1,122 @@
+import {createHmac, createHash, timingSafeEqual} from 'node:crypto';
+import {AwsClient} from 'aws4fetch';
+
+export class Problem extends Error {
+  constructor(status, code) { super(code); this.status = status; }
+}
+const fail = (status, code) => { throw new Problem(status, code); };
+const response = (body, status = 200) => Response.json(body, {status, headers: {
+  'Cache-Control': 'private, no-store, max-age=0', 'X-Content-Type-Options': 'nosniff',
+}});
+export function validateConfig(config) {
+  if (!config?.s3?.accessKeyId || !config.s3.secretAccessKey || !config.s3.region) throw Error('Missing storage configuration');
+  if (!config.clients || !Object.keys(config.clients).length) throw Error('Missing client configuration');
+  for (const [id, client] of Object.entries(config.clients)) {
+    if (!/^[a-z0-9-]{1,50}$/.test(id) || !/^[A-Za-z0-9_-]{43,128}$/.test(client.secret) ||
+        !Array.isArray(client.buckets) || !client.buckets.length ||
+        client.buckets.some(b => !/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(b))) throw Error('Invalid client configuration');
+  }
+  return config;
+}
+export function createDownloadService({config, channels, snapshot, request = fetch, now = Date.now}) {
+  validateConfig(config);
+  if (!Array.isArray(channels) || !channels.length || channels.length > 4 ||
+      channels.some(c => !/^[a-z0-9.-]+$/.test(c.hostname))) throw Error('Invalid channels');
+  const aws = new AwsClient({...config.s3, service: 's3'}), seen = new Map();
+  let cursor = 0, active = 0;
+  const stats = {issued: 0, metadata: 0, denied: 0, unavailable: 0};
+  const accepting = () => {
+    const state = snapshot();
+    if (now() - Date.parse(state.checkedAt) > 15000 || Date.parse(state.checkedAt) > now() + 5000 ||
+        !Number.isFinite(Date.parse(state.checkedAt))) fail(503, 'storage_unavailable');
+    return channels.filter(c => state.channels.some(s => s.id === c.id && s.hostname === c.hostname && s.state === 'ready' && s.healthy));
+  };
+  async function sign(endpoint, bucket, key, ttl, method, filename) {
+    const url = new URL(endpoint + '/' + [bucket, ...key.split('/')].map(encodeURIComponent).join('/'));
+    url.searchParams.set('X-Amz-Expires', String(ttl));
+    if (filename) url.searchParams.set('response-content-disposition', `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`);
+    return (await aws.sign(url.toString(), {method, aws: {signQuery: true}})).url;
+  }
+  async function select(bucket, key) {
+    const candidates = accepting();
+    if (!candidates.length) fail(503, 'storage_unavailable');
+    const order = candidates.map((_, i) => candidates[(cursor + i) % candidates.length]);
+    cursor = (cursor + 1) % candidates.length;
+    async function check(channel) {
+      const endpoint = 'https://' + channel.hostname;
+      const ready = await request(endpoint + '/channel-ready', {method: 'HEAD', redirect: 'error', signal: AbortSignal.timeout(2000)});
+      if (ready.status !== 200) throw Error('Unavailable');
+      const metadata = await request(await sign(endpoint, bucket, key, 15, 'HEAD'), {method: 'HEAD', redirect: 'error', signal: AbortSignal.timeout(3000)});
+      if (metadata.status !== 200 || !accepting().some(c => c.id === channel.id)) throw Error('Unavailable');
+      return {endpoint, metadata};
+    }
+    try { return await check(order[0]); }
+    catch {
+      try { return await Promise.any(order.slice(1).map(check)); }
+      catch { fail(503, 'storage_unavailable'); }
+    }
+  }
+  function authenticate(req, text, pathname) {
+    const id = req.headers.get('x-download-client') || '', client = config.clients[id];
+    const timestamp = req.headers.get('x-download-timestamp') || '', nonce = req.headers.get('x-download-nonce') || '';
+    const signature = req.headers.get('x-download-signature') || '';
+    if (!Object.hasOwn(config.clients, id) || !client || !/^\d{10}$/.test(timestamp) ||
+        !/^[A-Za-z0-9_-]{20,100}$/.test(nonce) || !/^[0-9a-f]{64}$/.test(signature)) fail(401, 'unauthorized');
+    const age = Math.floor(now() / 1000) - Number(timestamp);
+    if (age < -5 || age > 30) fail(401, 'unauthorized');
+    const digest = createHash('sha256').update(text).digest('hex');
+    const message = ['download-agent-v1', id, req.method, pathname, timestamp, nonce, digest].join('\n');
+    const expected = createHmac('sha256', client.secret).update(message).digest();
+    if (!timingSafeEqual(expected, Buffer.from(signature, 'hex'))) fail(401, 'unauthorized');
+    for (const [k, expires] of seen) if (expires < now()) seen.delete(k);
+    const nonceKey = id + ':' + nonce;
+    if (seen.has(nonceKey)) fail(409, 'replayed_request');
+    if (seen.size >= 10000) fail(429, 'busy');
+    // Consume before I/O: simultaneous copies cannot both issue links.
+    seen.set(nonceKey, (Number(timestamp) + 31) * 1000);
+    return client;
+  }
+  async function handle(req) {
+    let reserved = false;
+    try {
+      const url = new URL(req.url);
+      if (req.method === 'GET' && url.pathname === '/healthz' && !url.search) return response({ok: true});
+      if (req.method !== 'POST' || url.search || !['/v1/downloads', '/v1/objects/stat'].includes(url.pathname)) fail(404, 'not_found');
+      if (req.headers.has('origin')) fail(403, 'server_only');
+      if (!req.headers.get('content-type')?.startsWith('application/json')) fail(415, 'json_required');
+      // Network adapter enforces this limit while reading, before buffering.
+      const text = await req.text();
+      if (Buffer.byteLength(text) > 8192) fail(413, 'request_too_large');
+      const client = authenticate(req, text, url.pathname);
+      let body; try { body = JSON.parse(text); } catch { fail(400, 'invalid_input'); }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) fail(400, 'invalid_input');
+      const {bucket, key, filename, expiresAt} = body;
+      if (!client.buckets.includes(bucket)) fail(403, 'bucket_not_allowed');
+      if (typeof key !== 'string' || Buffer.byteLength(key) > 1024 || /[\\\x00-\x1f\x7f]/.test(key) ||
+          key.split('/').some(s => !s || s === '.' || s === '..')) fail(400, 'invalid_input');
+      const download = url.pathname === '/v1/downloads';
+      if (download && (typeof filename !== 'string' || !filename.length || filename.length > 200 ||
+          /[\/\\\x00-\x1f\x7f]/.test(filename) || !Number.isSafeInteger(expiresAt) || expiresAt > now() + 120000)) fail(400, 'invalid_input');
+      if (download && expiresAt <= now()) fail(403, 'grant_expired');
+      if (active >= 32) fail(429, 'busy');
+      active++; reserved = true;
+      const {endpoint, metadata} = await select(bucket, key);
+      if (!download) {
+        const size = Number(metadata.headers.get('content-length'));
+        if (!Number.isSafeInteger(size) || size < 1) fail(503, 'storage_unavailable');
+        stats.metadata++; return response({size_bytes: size});
+      }
+      const ttl = Math.min(120, Math.floor((expiresAt - now()) / 1000));
+      if (ttl < 1) fail(403, 'grant_expired');
+      const signed = await sign(endpoint, bucket, key, ttl, 'GET', filename);
+      if (expiresAt <= now()) fail(403, 'grant_expired');
+      stats.issued++;
+      return response({url: signed, filename, expires_in: ttl});
+    } catch (error) {
+      const status = error instanceof Problem ? error.status : 503;
+      stats[status >= 500 ? 'unavailable' : 'denied']++;
+      return response({error: error instanceof Problem ? error.message : 'storage_unavailable'}, status);
+    } finally { if (reserved) active--; }
+  }
+  return {handle, status: () => ({...stats, active})};
+}