@forgezero/providers 0.1.0

package/dist/storage.js

@@ -0,0 +1,441 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function staticConfig(services) {
+  const health = new Map;
+  return {
+    name: "static",
+    async list(serviceKey) {
+      return (services[serviceKey] ?? []).map((provider) => ({
+        ...provider,
+        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+      }));
+    },
+    async recordHealth(serviceKey, providerId, next) {
+      health.set(`${serviceKey}:${providerId}`, next);
+    }
+  };
+}
+function defineProvider(spec) {
+  return spec;
+}
+var STRIKES_TO_OFFLINE = 3;
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, args) {
+    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+    const attempts = [];
+    for (const entry of configured) {
+      const spec = byId.get(entry.providerId);
+      if (!spec) {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+        continue;
+      }
+      if (entry.health?.status === "offline") {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      options.before?.({ service: serviceKey, provider: entry.providerId });
+      try {
+        const result = await spec.invoke({
+          config: entry.config,
+          secret: (field) => options.credentials.get(entry.secretRef, field)
+        }, args);
+        attempts.push({ providerId: entry.providerId, outcome: "sent" });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, "success"));
+        const sent = { ok: true, result, provider: entry.providerId, attempts };
+        options.after?.(sent);
+        return sent;
+      } catch (error) {
+        const kind = spec.classify(error);
+        attempts.push({
+          providerId: entry.providerId,
+          outcome: "failed",
+          kind,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider is configured for "${serviceKey}".` : `Every provider for "${serviceKey}" failed or was skipped.`)
+    };
+    options.after?.(failed);
+    return failed;
+  }
+  return { call };
+}
+var VERSION = "0.1.0";
+
+// src/storage.ts
+var encoder = new TextEncoder;
+
+class StorageError extends ProviderError {
+  status;
+  constructor(code, message, status) {
+    super(code, message);
+    this.status = status;
+    this.name = "StorageError";
+  }
+}
+var MAX_SINGLE_PUT_BYTES = 5 * 1024 * 1024 * 1024;
+var hex = (buffer) => [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+var sha256Hex = async (data) => hex(await crypto.subtle.digest("SHA-256", typeof data === "string" ? encoder.encode(data) : data));
+async function hmac(key, message) {
+  const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign"
+  ]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", imported, encoder.encode(message)));
+}
+function encodeSegment(segment) {
+  return encodeURIComponent(segment).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+var encodeKey = (key) => key.split("/").map(encodeSegment).join("/");
+function amzDate(at) {
+  const full = at.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+  return { full, short: full.slice(0, 8) };
+}
+async function signRequest(args) {
+  const service = args.service ?? "s3";
+  const { full, short } = amzDate(args.at);
+  const headers = {
+    ...args.headers,
+    host: args.url.host,
+    "x-amz-content-sha256": args.payloadHash,
+    "x-amz-date": full,
+    ...args.credentials.sessionToken ? { "x-amz-security-token": args.credentials.sessionToken } : {}
+  };
+  const canonicalHeaderNames = Object.keys(headers).map((name) => name.toLowerCase()).sort();
+  const lower = Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+  const canonicalHeaders = canonicalHeaderNames.map((name) => `${name}:${String(lower[name]).trim()}
+`).join("");
+  const signedHeaders = canonicalHeaderNames.join(";");
+  const canonicalQuery = [...args.url.searchParams.entries()].map(([name, value]) => [encodeSegment(name), encodeSegment(value)]).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : 1).map(([name, value]) => `${name}=${value}`).join("&");
+  const canonicalRequest = [
+    args.method,
+    args.url.pathname,
+    canonicalQuery,
+    canonicalHeaders,
+    signedHeaders,
+    args.payloadHash
+  ].join(`
+`);
+  const scope = `${short}/${args.region}/${service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    full,
+    scope,
+    await sha256Hex(canonicalRequest)
+  ].join(`
+`);
+  let key = encoder.encode(`AWS4${args.credentials.secretAccessKey}`);
+  for (const part of [short, args.region, service, "aws4_request"])
+    key = await hmac(key, part);
+  const signature = hex(await hmac(key, stringToSign));
+  return {
+    url: args.url.toString(),
+    method: args.method,
+    headers: {
+      ...headers,
+      authorization: `AWS4-HMAC-SHA256 Credential=${args.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`
+    }
+  };
+}
+function createS3Client(config, credentials) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = config.timeoutMs ?? 30000;
+  const addressing = config.addressing ?? "path";
+  function urlFor(key, query = {}) {
+    const base = new URL(config.endpoint);
+    if (addressing === "virtual") {
+      base.host = `${config.bucket}.${base.host}`;
+      base.pathname = `/${encodeKey(key)}`;
+    } else {
+      base.pathname = key ? `/${encodeSegment(config.bucket)}/${encodeKey(key)}` : `/${encodeSegment(config.bucket)}`;
+    }
+    for (const [name, value] of Object.entries(query))
+      base.searchParams.set(name, value);
+    return base;
+  }
+  async function send(args) {
+    const payloadHash = await sha256Hex(args.body ?? "");
+    const signed = await signRequest({
+      method: args.method,
+      url: args.url,
+      region: config.region,
+      credentials,
+      payloadHash,
+      headers: args.headers,
+      at: new Date
+    });
+    const controller = new AbortController;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await doFetch(signed.url, {
+        method: signed.method,
+        headers: signed.headers,
+        signal: controller.signal,
+        ...args.body ? { body: args.body } : {}
+      });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new StorageError(`S3_${response.status}`, `${args.method} ${args.url.pathname} → ${response.status}. ${extractS3Message(detail) ?? detail.slice(0, 200)}`, response.status);
+      }
+      return response;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return {
+    async putObject(args) {
+      const body = typeof args.body === "string" ? encoder.encode(args.body) : args.body;
+      if (body.byteLength > MAX_SINGLE_PUT_BYTES) {
+        throw new StorageError("S3_TOO_LARGE", `${body.byteLength} bytes exceeds the ${MAX_SINGLE_PUT_BYTES}-byte single-request limit. This needs multipart upload, which this client does not implement.`);
+      }
+      const response = await send({
+        method: "PUT",
+        url: urlFor(args.key),
+        body,
+        headers: {
+          "content-type": args.contentType ?? "application/octet-stream",
+          ...Object.fromEntries(Object.entries(args.metadata ?? {}).map(([name, value]) => [`x-amz-meta-${name}`, value]))
+        }
+      });
+      return { etag: response.headers.get("etag") ?? undefined };
+    },
+    async getObject(key) {
+      const response = await send({ method: "GET", url: urlFor(key) });
+      return new Uint8Array(await response.arrayBuffer());
+    },
+    async headObject(key) {
+      try {
+        const response = await send({ method: "HEAD", url: urlFor(key) });
+        return {
+          key,
+          size: Number(response.headers.get("content-length") ?? 0),
+          etag: response.headers.get("etag") ?? undefined,
+          lastModified: response.headers.get("last-modified") ?? undefined
+        };
+      } catch (error) {
+        if (error instanceof StorageError && error.status === 404)
+          return null;
+        throw error;
+      }
+    },
+    async deleteObject(key) {
+      await send({ method: "DELETE", url: urlFor(key) });
+    },
+    async listObjects(prefix = "", limit = 1000) {
+      const found = [];
+      let token;
+      do {
+        const response = await send({
+          method: "GET",
+          url: urlFor("", {
+            "list-type": "2",
+            ...prefix ? { prefix } : {},
+            "max-keys": String(Math.min(1000, limit - found.length)),
+            ...token ? { "continuation-token": token } : {}
+          })
+        });
+        const xml = await response.text();
+        found.push(...parseListXml(xml));
+        token = between(xml, "<NextContinuationToken>", "</NextContinuationToken>");
+      } while (token && found.length < limit);
+      return found.slice(0, limit);
+    },
+    async presign(args) {
+      const expires = Math.min(args.expiresInSec ?? 300, 604800);
+      const at = new Date;
+      const { full, short } = amzDate(at);
+      const scope = `${short}/${config.region}/s3/aws4_request`;
+      const url = urlFor(args.key);
+      url.searchParams.set("X-Amz-Algorithm", "AWS4-HMAC-SHA256");
+      url.searchParams.set("X-Amz-Credential", `${credentials.accessKeyId}/${scope}`);
+      url.searchParams.set("X-Amz-Date", full);
+      url.searchParams.set("X-Amz-Expires", String(expires));
+      url.searchParams.set("X-Amz-SignedHeaders", "host");
+      if (credentials.sessionToken)
+        url.searchParams.set("X-Amz-Security-Token", credentials.sessionToken);
+      const signed = await signRequest({
+        method: args.method ?? "GET",
+        url,
+        region: config.region,
+        credentials,
+        payloadHash: "UNSIGNED-PAYLOAD",
+        at
+      });
+      const signature = /Signature=([a-f0-9]+)/.exec(signed.headers.authorization)?.[1] ?? "";
+      url.searchParams.set("X-Amz-Signature", signature);
+      return url.toString();
+    },
+    bucket: config.bucket,
+    endpoint: config.endpoint
+  };
+}
+var between = (text, open, close) => {
+  const start = text.indexOf(open);
+  if (start === -1)
+    return;
+  const end = text.indexOf(close, start + open.length);
+  return end === -1 ? undefined : text.slice(start + open.length, end);
+};
+var unescapeXml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+function parseListXml(xml) {
+  const objects = [];
+  for (const match of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+    const block = match[1];
+    const key = between(block, "<Key>", "</Key>");
+    if (!key)
+      continue;
+    objects.push({
+      key: unescapeXml(key),
+      size: Number(between(block, "<Size>", "</Size>") ?? 0),
+      etag: between(block, "<ETag>", "</ETag>")?.replace(/&quot;|"/g, ""),
+      lastModified: between(block, "<LastModified>", "</LastModified>")
+    });
+  }
+  return objects;
+}
+var extractS3Message = (xml) => {
+  const code = between(xml, "<Code>", "</Code>");
+  const message = between(xml, "<Message>", "</Message>");
+  return code || message ? `${code ?? ""}${code && message ? ": " : ""}${message ?? ""}` : undefined;
+};
+var s3 = defineProvider({
+  id: "s3",
+  service: "storage",
+  label: "S3-compatible storage",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    required: ["accessKeyId", "secretAccessKey"],
+    properties: {
+      accessKeyId: { type: "string", title: "Access key ID" },
+      secretAccessKey: { type: "string", title: "Secret access key", writeOnly: true },
+      sessionToken: { type: "string", title: "Session token", writeOnly: true }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    required: ["endpoint", "region", "bucket"],
+    properties: {
+      endpoint: { type: "string", title: "Endpoint", description: "https://s3.eu-central-1.amazonaws.com" },
+      region: { type: "string", title: "Region", default: "us-east-1" },
+      bucket: { type: "string", title: "Bucket" },
+      addressing: {
+        type: "string",
+        enum: ["path", "virtual"],
+        default: "path",
+        description: "Path style works everywhere except AWS itself; virtual style is bucket.host. Guessing wrong presents as a 404 rather than a configuration error."
+      }
+    }
+  },
+  async invoke(context, request) {
+    const config = context.config;
+    const client = createS3Client(config, {
+      accessKeyId: await context.secret("accessKeyId"),
+      secretAccessKey: await context.secret("secretAccessKey")
+    });
+    switch (request.op) {
+      case "put":
+        return client.putObject(request);
+      case "get":
+        return client.getObject(request.key);
+      case "head":
+        return client.headObject(request.key);
+      case "delete":
+        return client.deleteObject(request.key);
+      case "list":
+        return client.listObjects(request.prefix, request.limit);
+      case "presign":
+        return client.presign(request);
+    }
+  },
+  classify(error) {
+    const status = error.status;
+    if (status === 401 || status === 403)
+      return "retryable";
+    if (status === 404)
+      return "terminal";
+    if (status === 400 || status === 411 || status === 413)
+      return "terminal";
+    if (status === 429 || status === 503)
+      return "backoff";
+    return "retryable";
+  }
+});
+var storageProviders = [s3];
+export {
+  storageProviders,
+  signRequest,
+  s3,
+  parseListXml,
+  encodeSegment,
+  createS3Client,
+  amzDate,
+  StorageError,
+  MAX_SINGLE_PUT_BYTES
+};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
+  "name": "@forgezero/providers",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "default": "./dist/email.js"
+    },
+    "./chain": {
+      "types": "./dist/chain.d.ts",
+      "default": "./dist/chain.js"
+    },
+    "./database": {
+      "types": "./dist/database.d.ts",
+      "default": "./dist/database.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "default": "./dist/storage.js"
+    },
+    "./pool": {
+      "types": "./dist/pool.d.ts",
+      "default": "./dist/pool.js"
+    },
+    "./binance": {
+      "types": "./dist/binance.d.ts",
+      "default": "./dist/binance.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "bun build src/index.ts src/email.ts src/chain.ts src/database.ts src/http.ts src/pool.ts src/storage.ts src/binance.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/bun": "latest"
+  },
+  "description": "Service registry with priority, health and fallback. Bring your own credential and config sources.",
+  "keywords": [
+    "email",
+    "smtp",
+    "failover",
+    "fallback",
+    "service-registry",
+    "retry",
+    "s3",
+    "storage",
+    "object-storage"
+  ],
+  "license": "MIT",
+  "homepage": "https://forgezero.net/docs/providers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axxra/forgezero.git",
+    "directory": "packages/providers"
+  },
+  "bugs": "https://github.com/axxra/forgezero/issues",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgezero/runtime": "^0.1.0"
+  }
+}