@blamejs/core 0.4.1

package/lib/object-store/sigv4.js

@@ -0,0 +1,535 @@
+"use strict";
+/**
+ * SigV4 protocol adapter — AWS Signature Version 4.
+ *
+ * One signing implementation covers the entire S3-API-compatible family:
+ *   AWS S3, Cloudflare R2, Backblaze B2 (S3 endpoint), MinIO, Wasabi,
+ *   Tigris, DigitalOcean Spaces, IDrive e2, Linode Object Storage, Storj
+ *   (S3 gateway). Service identifier is always "s3" for object storage.
+ *
+ * Config:
+ *   {
+ *     endpoint:        'https://s3.us-west-2.amazonaws.com'  // or R2/MinIO/etc.
+ *     region:          'us-west-2'                            // required
+ *     bucket:          'my-bucket'                            // required
+ *     accessKeyId:     '...'                                  // required
+ *     secretAccessKey: '...'                                  // required
+ *     sessionToken:    '...'                                  // optional (STS)
+ *     pathStyle:       false                                  // virtual-hosted
+ *                                                             //  by default
+ *     timeoutMs:       C.TIME.seconds(30)
+ *   }
+ *
+ * Reference:
+ *   https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
+ */
+var nodeCrypto = require("crypto");
+var { URL } = require("url");
+var { Readable } = require("stream");
+var safeXml = require("../parsers/safe-xml");
+var C = require("../constants");
+var { ObjectStoreError } = require("../framework-error");
+var httpClient = require("../http-client");
+var safeUrl = require("../safe-url");
+
+// S3 list responses are commonly 1000-key paginated payloads — well above
+// the parser's default 1 MiB / 10K element ceilings. These overrides
+// give headroom for normal responses without uncapping the parser.
+var LIST_PARSE_OPTS = {
+  maxBytes:    C.BYTES.mib(8),
+  maxElements: 50000,
+};
+
+function _arrayify(value) {
+  // xml-safe maps multiple same-tag children to an array; a single child
+  // stays as the bare object; zero children means the property is absent.
+  // List traversal needs a uniform array, so normalize.
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+var SERVICE = "s3";
+var ALGORITHM = "AWS4-HMAC-SHA256";
+
+// Presigned-URL expiry bounds. The SigV4 spec caps query-string-signed
+// URLs at 7 days; below 1 second is effectively unsignable.
+var PRESIGN_DEFAULT_EXPIRES_SECONDS = 15 * 60;        // 15 minutes
+var PRESIGN_MAX_EXPIRES_SECONDS     = 7 * 24 * 60 * 60; // 7 days (SigV4 hard cap)
+var PRESIGN_MIN_EXPIRES_SECONDS     = 1;
+
+var _err = ObjectStoreError.factory;
+
+// ---- SigV4 primitives ----
+
+function sha256Hex(buf) {
+  return nodeCrypto.createHash("sha256").update(buf).digest("hex");
+}
+function hmacSha256(key, data) {
+  return nodeCrypto.createHmac("sha256", key).update(data).digest();
+}
+
+// AWS-style URI encoding: same as RFC 3986 except path '/' may be preserved.
+function awsUriEncode(str, encodeSlash) {
+  var out = "";
+  for (var i = 0; i < str.length; i++) {
+    var c = str.charCodeAt(i);
+    var ch = str.charAt(i);
+    if ((c >= 0x41 && c <= 0x5A) || (c >= 0x61 && c <= 0x7A) ||
+        (c >= 0x30 && c <= 0x39) ||
+        ch === "-" || ch === "_" || ch === "." || ch === "~") {
+      out += ch;
+    } else if (ch === "/" && !encodeSlash) {
+      out += "/";
+    } else {
+      var enc = encodeURIComponent(ch).replace(/!/g, "%21").replace(/\*/g, "%2A").replace(/'/g, "%27").replace(/\(/g, "%28").replace(/\)/g, "%29");
+      out += enc;
+    }
+  }
+  return out;
+}
+
+function canonicalQueryString(searchParams) {
+  if (!searchParams || searchParams.toString() === "") return "";
+  var pairs = [];
+  searchParams.forEach(function (v, k) { pairs.push([k, v]); });
+  pairs.sort(function (a, b) {
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    if (a[1] < b[1]) return -1;
+    if (a[1] > b[1]) return 1;
+    return 0;
+  });
+  return pairs.map(function (p) {
+    return awsUriEncode(p[0], true) + "=" + awsUriEncode(p[1], true);
+  }).join("&");
+}
+
+function canonicalHeaders(headers) {
+  var pairs = [];
+  for (var k in headers) {
+    if (headers[k] === undefined || headers[k] === null) continue;
+    var lk = k.toLowerCase();
+    var v = String(headers[k]).trim().replace(/\s+/g, " ");
+    pairs.push([lk, v]);
+  }
+  pairs.sort(function (a, b) { return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0; });
+  var canon = "";
+  var signed = [];
+  for (var i = 0; i < pairs.length; i++) {
+    canon += pairs[i][0] + ":" + pairs[i][1] + "\n";
+    signed.push(pairs[i][0]);
+  }
+  return { canonical: canon, signed: signed.join(";") };
+}
+
+function canonicalRequest(method, urlObj, headers, payloadHash) {
+  var canonHeaders = canonicalHeaders(headers);
+  var path = urlObj.pathname;
+  if (!path) path = "/";
+  return [
+    method.toUpperCase(),
+    awsUriEncode(path, false),
+    canonicalQueryString(urlObj.searchParams),
+    canonHeaders.canonical,
+    canonHeaders.signed,
+    payloadHash,
+  ].join("\n");
+}
+
+function stringToSign(amzDate, credentialScope, canonicalReq) {
+  return [
+    ALGORITHM,
+    amzDate,
+    credentialScope,
+    sha256Hex(canonicalReq),
+  ].join("\n");
+}
+
+function deriveSigningKey(secretAccessKey, dateStamp, region, service) {
+  var kDate    = hmacSha256("AWS4" + secretAccessKey, dateStamp);
+  var kRegion  = hmacSha256(kDate, region);
+  var kService = hmacSha256(kRegion, service);
+  return hmacSha256(kService, "aws4_request");
+}
+
+function _formatAmzDate(d) {
+  var iso = d.toISOString().replace(/[-:]/g, "");
+  return iso.slice(0, 8) + "T" + iso.slice(9, 15) + "Z";
+}
+function _formatDateStamp(d) {
+  return d.toISOString().slice(0, 10).replace(/-/g, "");
+}
+
+function signRequest(opts) {
+  var date = opts.date || new Date();
+  var amzDate = _formatAmzDate(date);
+  var dateStamp = _formatDateStamp(date);
+  var url = opts.url instanceof URL ? opts.url : new URL(opts.url);
+
+  var headers = Object.assign({}, opts.headers || {});
+  headers["host"] = url.host;
+  headers["x-amz-date"] = amzDate;
+  if (!headers["x-amz-content-sha256"]) {
+    headers["x-amz-content-sha256"] = opts.payloadHash;
+  }
+  if (opts.sessionToken) {
+    headers["x-amz-security-token"] = opts.sessionToken;
+  }
+
+  var canon = canonicalRequest(opts.method, url, headers, opts.payloadHash);
+  var credentialScope = dateStamp + "/" + opts.region + "/" + SERVICE + "/aws4_request";
+  var sts = stringToSign(amzDate, credentialScope, canon);
+  var signingKey = deriveSigningKey(opts.secretAccessKey, dateStamp, opts.region, SERVICE);
+  var signature = nodeCrypto.createHmac("sha256", signingKey).update(sts).digest("hex");
+
+  var canonHeaders = canonicalHeaders(headers);
+  var auth = ALGORITHM +
+    " Credential=" + opts.accessKeyId + "/" + credentialScope +
+    ", SignedHeaders=" + canonHeaders.signed +
+    ", Signature=" + signature;
+  headers["Authorization"] = auth;
+
+  return { headers: headers, signature: signature, canonicalRequest: canon, stringToSign: sts };
+}
+
+// ---- HTTP request helper ----
+
+function _request(method, url, headers, body, opts) {
+  return httpClient.request({
+    method:           method,
+    url:              url,
+    headers:          headers,
+    body:             body,
+    idleTimeoutMs:    opts && opts.timeoutMs,
+    maxResponseBytes: opts && opts.maxResponseBytes,
+    errorClass:       ObjectStoreError,
+    allowedProtocols: opts && opts.allowedProtocols,
+  });
+}
+
+// ---- Public adapter factory ----
+
+function create(config) {
+  if (!config) throw new Error("sigv4 protocol requires config");
+  if (!config.region)          throw new Error("sigv4: region is required");
+  if (!config.bucket)          throw new Error("sigv4: bucket is required");
+  if (!config.accessKeyId)     throw new Error("sigv4: accessKeyId is required");
+  if (!config.secretAccessKey) throw new Error("sigv4: secretAccessKey is required");
+
+  var endpoint = config.endpoint || ("https://s3." + config.region + ".amazonaws.com");
+  if (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
+  var pathStyle = !!(config.pathStyle || config.forcePathStyle);
+  // HTTPS-only by default — AWS S3, R2, MinIO-over-https. Operators with
+  // an internal cleartext S3-compatible endpoint (test fixtures, local
+  // dev MinIO) opt in via config.allowedProtocols.
+  var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  safeUrl.parse(endpoint, {
+    allowedProtocols: allowedProtocols,
+    errorClass:       ObjectStoreError,
+  });
+  var reqOpts = { timeoutMs: config.timeoutMs, allowedProtocols: allowedProtocols };
+
+  function _keyToUrl(key) {
+    if (key.indexOf("\0") !== -1) throw _err("INVALID_KEY", "null byte in key", true);
+    var encoded = key.split("/").map(function (s) { return awsUriEncode(s, true); }).join("/");
+    if (pathStyle) {
+      return new URL(endpoint + "/" + config.bucket + "/" + encoded);
+    }
+    var u = new URL(endpoint);
+    u.hostname = config.bucket + "." + u.hostname;
+    u.pathname = "/" + encoded;
+    return u;
+  }
+
+  function _bucketUrl(searchParams) {
+    var u;
+    if (pathStyle) {
+      u = new URL(endpoint + "/" + config.bucket + "/");
+    } else {
+      u = new URL(endpoint);
+      u.hostname = config.bucket + "." + u.hostname;
+      u.pathname = "/";
+    }
+    if (searchParams) {
+      Object.keys(searchParams).forEach(function (k) { u.searchParams.set(k, searchParams[k]); });
+    }
+    return u;
+  }
+
+  function _makeSigned(method, url, payloadHash, extraHeaders) {
+    var signed = signRequest({
+      method:          method,
+      url:             url,
+      headers:         extraHeaders || {},
+      payloadHash:     payloadHash,
+      region:          config.region,
+      accessKeyId:     config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      sessionToken:    config.sessionToken,
+    });
+    return signed.headers;
+  }
+
+  function put(key, body, opts) {
+    var url = _keyToUrl(key);
+    var buf = Buffer.isBuffer(body) ? body : Buffer.from(typeof body === "string" ? body : "", "utf8");
+    var payloadHash = sha256Hex(buf);
+    var contentType = (opts && opts.contentType) || "application/octet-stream";
+    var headers = _makeSigned("PUT", url, payloadHash, {
+      "Content-Type":   contentType,
+      "Content-Length": String(buf.length),
+    });
+    return _request("PUT", url, headers, buf, reqOpts).then(function (res) {
+      return { size: buf.length, etag: res.headers.etag };
+    });
+  }
+
+  function get(key) {
+    var url = _keyToUrl(key);
+    var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));
+    return _request("GET", url, headers, null, reqOpts).then(function (res) {
+      return res.body;
+    });
+  }
+
+  function getStream(key) {
+    return Readable.from(get(key));
+  }
+
+  function head(key) {
+    var url = _keyToUrl(key);
+    var headers = _makeSigned("HEAD", url, sha256Hex(Buffer.alloc(0)));
+    return _request("HEAD", url, headers, null, reqOpts).then(function (res) {
+      return {
+        size:         res.headers["content-length"] ? parseInt(res.headers["content-length"], 10) : null,
+        etag:         res.headers.etag,
+        lastModified: res.headers["last-modified"] ? Date.parse(res.headers["last-modified"]) : null,
+      };
+    });
+  }
+
+  function deleteKey(key) {
+    var url = _keyToUrl(key);
+    var headers = _makeSigned("DELETE", url, sha256Hex(Buffer.alloc(0)));
+    return _request("DELETE", url, headers, null, reqOpts).then(
+      function () { return true; },
+      function (e) { if (e.statusCode === 404) return false; throw e; }
+    );
+  }
+
+  function _presign(method, opts) {
+    opts = opts || {};
+    if (!opts.key || typeof opts.key !== "string") {
+      throw _err("INVALID_KEY", "presigned URL: key is required", true);
+    }
+    if (opts.key.indexOf("\0") !== -1) {
+      throw _err("INVALID_KEY", "null byte in key", true);
+    }
+    var expiresIn = opts.expiresIn != null ? opts.expiresIn : PRESIGN_DEFAULT_EXPIRES_SECONDS;
+    if (typeof expiresIn !== "number" ||
+        expiresIn < PRESIGN_MIN_EXPIRES_SECONDS ||
+        expiresIn > PRESIGN_MAX_EXPIRES_SECONDS) {
+      throw _err("INVALID_EXPIRES",
+        "presigned URL: expiresIn must be a number of seconds between " +
+        PRESIGN_MIN_EXPIRES_SECONDS + " and " + PRESIGN_MAX_EXPIRES_SECONDS +
+        " (7 days, SigV4 hard cap)", true);
+    }
+
+    var url = _keyToUrl(opts.key);
+    var date = opts.date || new Date();
+    var amzDate = _formatAmzDate(date);
+    var dateStamp = _formatDateStamp(date);
+    var credentialScope = dateStamp + "/" + config.region + "/" + SERVICE + "/aws4_request";
+
+    // Build the headers we want to sign. host is always signed; if the
+    // caller supplies opts.contentType the value is bound into the
+    // signature so the client MUST send Content-Type matching exactly,
+    // otherwise S3 rejects with SignatureDoesNotMatch — turning the
+    // hint into real server-side enforcement.
+    var headers = { host: url.host };
+    if (opts.contentType) headers["content-type"] = opts.contentType;
+    var signedHeadersStr = Object.keys(headers).sort().join(";");
+
+    // Query-string SigV4: presigning carries auth in the URL itself.
+    // The set order doesn't matter — canonicalQueryString sorts the
+    // params before hashing.
+    url.searchParams.set("X-Amz-Algorithm", ALGORITHM);
+    url.searchParams.set("X-Amz-Credential", config.accessKeyId + "/" + credentialScope);
+    url.searchParams.set("X-Amz-Date", amzDate);
+    url.searchParams.set("X-Amz-Expires", String(expiresIn));
+    url.searchParams.set("X-Amz-SignedHeaders", signedHeadersStr);
+    if (config.sessionToken) {
+      url.searchParams.set("X-Amz-Security-Token", config.sessionToken);
+    }
+
+    // Payload hash for query-string presigning is the literal string
+    // "UNSIGNED-PAYLOAD" — the body is not part of the signature.
+    var canon = canonicalRequest(method, url, headers, "UNSIGNED-PAYLOAD");
+    var sts = stringToSign(amzDate, credentialScope, canon);
+    var signingKey = deriveSigningKey(config.secretAccessKey, dateStamp, config.region, SERVICE);
+    var signature = nodeCrypto.createHmac("sha256", signingKey).update(sts).digest("hex");
+
+    url.searchParams.set("X-Amz-Signature", signature);
+
+    var clientHeaders = {};
+    if (opts.contentType) clientHeaders["Content-Type"] = opts.contentType;
+
+    return {
+      url:       url.toString(),
+      method:    method,
+      headers:   clientHeaders,
+      expiresAt: date.getTime() + C.TIME.seconds(expiresIn),
+    };
+  }
+
+  function presignedUploadUrl(opts)   { return _presign("PUT", opts); }
+  function presignedDownloadUrl(opts) { return _presign("GET", opts); }
+
+  // POST-form policy presigning (S3-compatible). Unlike query-string
+  // PUT presigning, this lets the operator enforce body-size at the
+  // upload endpoint via the `content-length-range` policy condition.
+  // Clients upload via multipart/form-data POST to the returned URL,
+  // attaching every key in `fields` plus the file as the last field.
+  //
+  // Reference: AWS S3 "Browser-Based Uploads Using POST".
+  function presignedUploadPolicy(opts) {
+    opts = opts || {};
+    if (!opts.key || typeof opts.key !== "string") {
+      throw _err("INVALID_KEY", "presignedUploadPolicy: key is required", true);
+    }
+    if (opts.key.indexOf("\0") !== -1) {
+      throw _err("INVALID_KEY", "null byte in key", true);
+    }
+    if (typeof opts.maxBytes !== "number" || !Number.isFinite(opts.maxBytes) ||
+        opts.maxBytes <= 0) {
+      throw _err("INVALID_MAX_BYTES",
+        "presignedUploadPolicy: maxBytes (positive number of bytes) is required — " +
+        "POST-form policy enforces body size via the content-length-range condition; " +
+        "use presignedUploadUrl if size enforcement is not needed", true);
+    }
+    var minBytes = (typeof opts.minBytes === "number" && opts.minBytes >= 0) ? opts.minBytes : 0;
+    var expiresIn = opts.expiresIn != null ? opts.expiresIn : PRESIGN_DEFAULT_EXPIRES_SECONDS;
+    if (typeof expiresIn !== "number" ||
+        expiresIn < PRESIGN_MIN_EXPIRES_SECONDS ||
+        expiresIn > PRESIGN_MAX_EXPIRES_SECONDS) {
+      throw _err("INVALID_EXPIRES",
+        "presignedUploadPolicy: expiresIn must be a number of seconds between " +
+        PRESIGN_MIN_EXPIRES_SECONDS + " and " + PRESIGN_MAX_EXPIRES_SECONDS +
+        " (7 days, SigV4 hard cap)", true);
+    }
+
+    var date = opts.date || new Date();
+    var amzDate = _formatAmzDate(date);
+    var dateStamp = _formatDateStamp(date);
+    var credentialScope = dateStamp + "/" + config.region + "/" + SERVICE + "/aws4_request";
+    var credential = config.accessKeyId + "/" + credentialScope;
+    var expirationIso = new Date(date.getTime() + C.TIME.seconds(expiresIn)).toISOString();
+
+    // Policy conditions. Each entry must MATCH a corresponding form
+    // field exactly OR be a structural constraint (content-length-range
+    // / starts-with). Order doesn't matter — S3 evaluates the set.
+    var conditions = [
+      { "bucket":           config.bucket },
+      { "key":              opts.key },
+      { "x-amz-algorithm":  ALGORITHM },
+      { "x-amz-credential": credential },
+      { "x-amz-date":       amzDate },
+      ["content-length-range", minBytes, opts.maxBytes],
+    ];
+    if (config.sessionToken) {
+      conditions.push({ "x-amz-security-token": config.sessionToken });
+    }
+    if (opts.contentType) {
+      conditions.push({ "content-type": opts.contentType });
+    }
+
+    var policy = { expiration: expirationIso, conditions: conditions };
+    var policyJson = JSON.stringify(policy);
+    var policyB64 = Buffer.from(policyJson, "utf8").toString("base64");
+
+    var signingKey = deriveSigningKey(config.secretAccessKey, dateStamp, config.region, SERVICE);
+    var signature = nodeCrypto.createHmac("sha256", signingKey).update(policyB64).digest("hex");
+
+    var fields = {
+      "key":              opts.key,
+      "x-amz-algorithm":  ALGORITHM,
+      "x-amz-credential": credential,
+      "x-amz-date":       amzDate,
+      "policy":           policyB64,
+      "x-amz-signature":  signature,
+    };
+    if (config.sessionToken) fields["x-amz-security-token"] = config.sessionToken;
+    if (opts.contentType)    fields["content-type"]         = opts.contentType;
+
+    // The bucket-root URL — no key in the path, key is a form field.
+    var url = _bucketUrl();
+
+    return {
+      url:           url.toString(),
+      method:        "POST",
+      fields:        fields,
+      expiresAt:     date.getTime() + C.TIME.seconds(expiresIn),
+      maxBytes:      opts.maxBytes,
+      enforcement:   "content-length-range",  // S3-side enforced
+    };
+  }
+
+  function list(prefix, opts) {
+    opts = opts || {};
+    var params = { "list-type": "2" };
+    if (prefix) params["prefix"] = prefix;
+    if (opts.maxResults) params["max-keys"] = String(opts.maxResults);
+    if (opts.continuationToken) params["continuation-token"] = opts.continuationToken;
+
+    var url = _bucketUrl(params);
+    var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));
+    return _request("GET", url, headers, null, reqOpts).then(function (res) {
+      var doc = safeXml.parse(res.body, LIST_PARSE_OPTS);
+      var result = doc.ListBucketResult || {};
+      var contents = _arrayify(result.Contents);
+      var items = contents.map(function (c) {
+        return {
+          key:          c.Key,
+          size:         c.Size != null ? parseInt(c.Size, 10) : null,
+          lastModified: c.LastModified ? Date.parse(c.LastModified) : null,
+        };
+      }).filter(function (it) { return it.key; });
+      return {
+        items:             items,
+        truncated:         result.IsTruncated === "true",
+        continuationToken: result.NextContinuationToken || null,
+      };
+    });
+  }
+
+  return {
+    protocol:  "sigv4",
+    endpoint:  endpoint,
+    bucket:    config.bucket,
+    region:    config.region,
+    pathStyle: pathStyle,
+    put:       put,
+    get:       get,
+    getStream: getStream,
+    head:      head,
+    delete:    deleteKey,
+    list:      list,
+    presignedUploadUrl:    presignedUploadUrl,
+    presignedDownloadUrl:  presignedDownloadUrl,
+    presignedUploadPolicy: presignedUploadPolicy,
+  };
+}
+
+module.exports = {
+  create:               create,
+  signRequest:          signRequest,
+  canonicalRequest:     canonicalRequest,
+  stringToSign:         stringToSign,
+  deriveSigningKey:     deriveSigningKey,
+  canonicalQueryString: canonicalQueryString,
+  canonicalHeaders:     canonicalHeaders,
+  awsUriEncode:         awsUriEncode,
+  sha256Hex:            sha256Hex,
+  SERVICE:              SERVICE,
+  ALGORITHM:            ALGORITHM,
+};

package/lib/observability.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * observability — combined metrics + tracing tap surface.
+ *
+ * Framework hot paths previously called metrics.tap + tracing.tap
+ * separately, with each module repeating the lazy-require + try/catch
+ * boilerplate. This primitive folds the two into one helper:
+ *
+ *   var obs = require("./observability");
+ *   return obs.tap("audit.record",
+ *     { action: event.action, outcome: event.outcome },
+ *     async function (span) {
+ *       // ... operation body ...
+ *       return result;
+ *     });
+ *
+ * Behavior:
+ *   - tracing.tap wraps fn in a span (spec 9.8). Pass-through is
+ *     fn(null) when no tracing registry is active — zero overhead.
+ *   - After fn settles (either branch), metrics.tap fires once with
+ *     the same name + the same attrs reused as labels. Existing
+ *     metrics _tapHandler dispatches still work unchanged because
+ *     the labels are the same shape modules previously passed.
+ *   - If fn throws (sync) or rejects (async), metrics still fire
+ *     before the throw propagates. Operators get the counter bump
+ *     even on the failure path — the existing pattern across audit /
+ *     vault / queue did the same.
+ *
+ * Why combine: every framework module that wanted both a span AND a
+ * counter previously wrote nested tap wrappers + try/catch. Centralizing
+ * keeps the call sites readable, eliminates boot-order drift each
+ * module had to reason about, and lets us change tap semantics
+ * (e.g. add a third sink) in one place.
+ *
+ * For fire-and-forget value-noting where wrapping fn doesn't fit —
+ * incrementing a counter on a side-effect deep inside an existing
+ * function — use `event(name, value, labels)`. Same shape as the
+ * legacy metrics.tap call; routes through metrics only (no span).
+ *
+ * Public API:
+ *   observability.tap(name, attrs, fn)        → fn's return value
+ *   observability.tap(name, fn)               → fn's return value (no attrs)
+ *   observability.event(name, value, labels)  → undefined
+ *
+ * Tests live in test/layer-0-primitives/observability.test.js.
+ *
+ * Parameters:
+ *   name: string — used as both the span name AND the metrics tap
+ *     name. Convention: dotted lowercase ("audit.record", "queue.enqueue").
+ *   attrs: object | null — passed verbatim to tracing.tap as span
+ *     attributes AND to metrics.tap as labels. Modules previously
+ *     passing two slightly-different objects to the two sinks should
+ *     pass one unified shape.
+ *   fn: function — sync or async. Return propagates; throws propagate
+ *     after metrics fire.
+ */
+var lazyRequire = require("./lazy-require");
+
+var tracing = lazyRequire(function () { return require("./tracing"); });
+var metrics = lazyRequire(function () { return require("./metrics"); });
+
+function _safeMetricsTap(name, value, labels) {
+  try { metrics().tap(name, value, labels); }
+  catch (_e) { /* boot-order tolerance — metrics may not be loaded */ }
+}
+
+function tap(name, attrs, fn) {
+  if (typeof attrs === "function") { fn = attrs; attrs = null; }
+  // Tier A validation: tap is called from many call sites and a typo
+  // in the name (e.g. variable holding undefined) silently corrupts both
+  // the span tree AND the metrics counter route, with no obvious symptom
+  // until somebody opens a dashboard. Throw at first call so the
+  // operator catches it.
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("observability.tap: name must be a non-empty string, got " +
+      (typeof name) + " " + JSON.stringify(name));
+  }
+  if (typeof fn !== "function") {
+    throw new TypeError("observability.tap: fn must be a function, got " + (typeof fn));
+  }
+  return tracing().tap(name, attrs, function (span) {
+    var ret;
+    try {
+      ret = fn(span);
+    } catch (e) {
+      _safeMetricsTap(name, 1, attrs);
+      throw e;
+    }
+    if (ret && typeof ret.then === "function") {
+      return ret.then(
+        function (v) { _safeMetricsTap(name, 1, attrs); return v; },
+        function (e) { _safeMetricsTap(name, 1, attrs); throw e; }
+      );
+    }
+    _safeMetricsTap(name, 1, attrs);
+    return ret;
+  });
+}
+
+// Tier B (drop-silent): event is the fire-and-forget shape called from
+// hot paths where throwing would crash the request that triggered it.
+// Bad input is silently dropped — operators with a misnamed event see
+// the missing counter, not a 500. metrics.tap performs its own label-
+// name regex validation; an invalid call surfaces in the metrics module
+// log, not via a thrown exception.
+function event(name, value, labels) {
+  if (typeof name !== "string" || name.length === 0) return;
+  _safeMetricsTap(name, value, labels);
+}
+
+module.exports = {
+  tap:   tap,
+  event: event,
+};