@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.

npm install @ailuntz/[email protected]

Backend integration:

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 resource-agent serve --runtime /runtime and resource-agent 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/resource-agent:1.1.1 installs this exact npm release and a pinned official cloudflared binary.