@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/client-hints.js

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * @module     b.clientHints
+ * @nav        HTTP
+ * @title      Sec-CH-UA Client Hints
+ * @order      316
+ *
+ * @intro
+ *   User-Agent Client Hints parser. Browsers replacing the
+ *   freeform `User-Agent` string send a family of `Sec-CH-UA-*`
+ *   request headers carrying structured-fields data per RFC 8941:
+ *
+ *     Sec-CH-UA: "Chromium";v="124", "Not-A.Brand";v="99", "Google Chrome";v="124"
+ *     Sec-CH-UA-Mobile: ?0
+ *     Sec-CH-UA-Platform: "Windows"
+ *     Sec-CH-UA-Platform-Version: "15.0.0"
+ *     Sec-CH-UA-Arch: "x86"
+ *     Sec-CH-UA-Bitness: "64"
+ *     Sec-CH-UA-Model: ""
+ *     Sec-CH-UA-Full-Version-List: "Chromium";v="124.0.6367.91", ...
+ *     Sec-CH-UA-WoW64: ?0
+ *     Sec-CH-UA-Form-Factors: "Desktop"
+ *
+ *   `parse(headers)` walks an HTTP request's headers map and returns
+ *   a normalized object — brand list with versions, mobile boolean,
+ *   platform / platform-version / arch / bitness / model / form-
+ *   factors strings — plus the raw RFC 8941 parsed shape for any
+ *   header the operator wants to inspect verbatim.
+ *
+ *   Operators use it to:
+ *     - Replace freeform UA-string parsing (deprecated; brittle).
+ *     - Negotiate per-platform CSS / JS bundles (Sec-CH-UA-Platform).
+ *     - Detect mobile-class clients without UA-sniffing.
+ *     - Audit fingerprinting-style header negotiation.
+ *
+ *   The primitive treats every header as defensive request-shape
+ *   input — returns `null` for absent / malformed headers, throws
+ *   only on explicit control-character / header-injection-shape
+ *   input. Operators upstream of this primitive (proxies, framework
+ *   middleware) already split CRLF; the in-string control-byte
+ *   check is a defense-in-depth layer.
+ *
+ *   `acceptList()` builds the `Accept-CH` response header so the
+ *   operator advertises which client-hint headers the page wants.
+ *
+ * @card
+ *   RFC 8941 / W3C Client Hints — parse `Sec-CH-UA*` request headers
+ *   (brand list, mobile, platform, arch, model, form-factors) and
+ *   build the `Accept-CH` response header for hint negotiation.
+ */
+
+var structuredFields = require("./structured-fields");
+var { defineClass } = require("./framework-error");
+
+var ClientHintsError = defineClass("ClientHintsError",
+  { alwaysPermanent: true });
+
+// Well-known Sec-CH-UA-* header names (W3C UA-CH spec + IETF
+// draft-davidben-http-client-hint-reliability). Operators looking up
+// the canonical name for an Accept-CH response use this constant; we
+// keep it as a frozen array so a future hint addition is one-line.
+var KNOWN_HINTS = Object.freeze([
+  "Sec-CH-UA",
+  "Sec-CH-UA-Mobile",
+  "Sec-CH-UA-Platform",
+  "Sec-CH-UA-Platform-Version",
+  "Sec-CH-UA-Arch",
+  "Sec-CH-UA-Bitness",
+  "Sec-CH-UA-Model",
+  "Sec-CH-UA-Full-Version-List",
+  "Sec-CH-UA-WoW64",
+  "Sec-CH-UA-Form-Factors",
+  "Sec-CH-Prefers-Reduced-Motion",
+  "Sec-CH-Prefers-Reduced-Transparency",
+  "Sec-CH-Prefers-Color-Scheme",
+  "Sec-CH-Prefers-Contrast",
+  "Sec-CH-Save-Data",
+  "Sec-CH-Viewport-Width",
+  "Sec-CH-Viewport-Height",
+  "Sec-CH-DPR",
+  "Sec-CH-Width",
+  "Sec-CH-Downlink",
+  "Sec-CH-RTT",
+  "Sec-CH-ECT",
+]);
+
+var KNOWN_HINTS_LC = {};
+for (var _h = 0; _h < KNOWN_HINTS.length; _h += 1) {
+  KNOWN_HINTS_LC[KNOWN_HINTS[_h].toLowerCase()] = KNOWN_HINTS[_h];
+}
+
+function _scanControlBytes(s, headerName) {
+  structuredFields.refuseControlBytes(s, {
+    ErrorClass: ClientHintsError,
+    code:       "client-hints/bad-header-value",
+    label:      "parse: " + headerName,
+  });
+}
+
+// RFC 8941 §3.3.3 sf-string — quoted-string with backslash-escape for
+// `"` and `\`. Defensive parser that tolerates unquoted bare tokens
+// (some operators forward a header whose quote-shape was already
+// stripped by an upstream proxy).
+function _parseSfString(s) {
+  var t = s.trim();
+  if (t.length === 0) return "";
+  if (t.charAt(0) === "\"") {
+    if (t.charAt(t.length - 1) !== "\"") return null;
+    return t.slice(1, -1).replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+  }
+  return t;
+}
+
+// RFC 8941 §3.3.6 sf-boolean — `?1` (true) / `?0` (false). Returns
+// null for any other shape so callers can detect malformed values.
+function _parseSfBoolean(s) {
+  var t = s.trim();
+  if (t === "?1") return true;
+  if (t === "?0") return false;
+  return null;
+}
+
+// RFC 8941 §3.1.1 sf-list — comma-separated members, each potentially
+// carrying `;key=value;flag` parameters. For Sec-CH-UA the members are
+// sf-strings with a `;v="<version>"` parameter giving the brand
+// version. Returns `[ { brand, version, params } ]` or `null` for
+// malformed input.
+function _parseSfBrandList(s) {
+  var t = s.trim();
+  if (t.length === 0) return [];
+  // Walk via the shared quote-aware top-level `,` splitter. RFC 8941
+  // sf-list members don't allow parenthesized inner-list values in
+  // the Sec-CH-UA grammar (only sf-string + parameters), so the
+  // simple top-level comma split suffices — no `depth` tracking
+  // needed (the earlier inline shape carried defensive paren
+  // tracking left over from a generic sf-list walker prototype).
+  var pieces = structuredFields.splitTopLevel(t, ",");
+  var out = [];
+  for (var i = 0; i < pieces.length; i += 1) {
+    var piece = pieces[i].trim();
+    if (piece.length === 0) continue;
+    var parsed = _parseBrandMember(piece);
+    if (parsed !== null) out.push(parsed);
+  }
+  return out;
+}
+
+function _parseBrandMember(piece) {
+  // member ::= sf-string ( ';' parameter )*
+  // RFC 8941 §4.1.1.4 — parameter values can be sf-string. A bare
+  // `piece.split(";")` would slice through `;v="1.2; 3"` and corrupt
+  // the parameter value. Use the shared quote-aware splitter so the
+  // tracking shape stays consistent across every framework parser.
+  var params = structuredFields.splitTopLevel(piece, ";");
+  if (params.length === 0) return null;
+  var brand = _parseSfString(params[0].trim());
+  if (brand === null) return null;
+  var member = { brand: brand, version: null, params: {} };
+  for (var i = 1; i < params.length; i += 1) {
+    var kv = params[i].trim();
+    if (kv.length === 0) continue;
+    var eq = kv.indexOf("=");
+    if (eq === -1) { member.params[kv.toLowerCase()] = true; continue; }
+    var k = kv.slice(0, eq).trim().toLowerCase();
+    var v = _parseSfString(kv.slice(eq + 1));
+    member.params[k] = v;
+    if (k === "v" && v !== null) member.version = v;
+  }
+  return member;
+}
+
+/**
+ * @primitive b.clientHints.parse
+ * @signature b.clientHints.parse(headers)
+ * @since     0.8.91
+ * @status    stable
+ * @related   b.clientHints.acceptList, b.clientHints.isKnownHint
+ *
+ * Parse the Sec-CH-UA-* family from an HTTP request's headers object.
+ * `headers` is the Node `req.headers` shape (header names are
+ * already lowercased per Node convention). Returns a normalized
+ * `{ brands, mobile, platform, platformVersion, arch, bitness, model,
+ *    fullVersionList, wow64, formFactors, raw }` shape:
+ *
+ *   - `brands`: `[ { brand, version, params } ]` from `Sec-CH-UA`
+ *   - `mobile`: boolean from `Sec-CH-UA-Mobile` (?1/?0) — null if absent / malformed
+ *   - `platform`: sf-string from `Sec-CH-UA-Platform`
+ *   - `platformVersion`: sf-string from `Sec-CH-UA-Platform-Version`
+ *   - `arch`: sf-string from `Sec-CH-UA-Arch`
+ *   - `bitness`: sf-string from `Sec-CH-UA-Bitness`
+ *   - `model`: sf-string from `Sec-CH-UA-Model`
+ *   - `fullVersionList`: brand-list from `Sec-CH-UA-Full-Version-List`
+ *   - `wow64`: boolean from `Sec-CH-UA-WoW64`
+ *   - `formFactors`: brand-list from `Sec-CH-UA-Form-Factors`
+ *   - `raw`: `{ "<header-name-lc>": "<raw-value>" }` for every Sec-CH-*
+ *     header in the input, so operators can audit the full set without
+ *     re-walking `req.headers`.
+ *
+ * Returns `null` when `headers` is not an object. Individual fields
+ * are `null` when the corresponding header is absent or malformed
+ * (defensive request-shape reader). Refuses control characters in
+ * any present Sec-CH-* value (header-injection defense).
+ *
+ * @example
+ *   var ch = b.clientHints.parse(req.headers);
+ *   if (ch && ch.mobile === true) renderMobilePage(req, res);
+ *   else if (ch && ch.platform === "Windows") renderWindowsPage(req, res);
+ *   else renderDefaultPage(req, res);
+ */
+function parse(headers) {
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) return null;
+  var raw = {};
+  var keys = Object.keys(headers);
+  for (var k = 0; k < keys.length; k += 1) {
+    var name = keys[k].toLowerCase();
+    if (name.indexOf("sec-ch-") !== 0) continue;
+    var val = headers[keys[k]];
+    if (val === undefined || val === null) continue;
+    if (typeof val !== "string") val = String(val);
+    _scanControlBytes(val, name);
+    raw[name] = val;
+  }
+
+  return {
+    brands:           raw["sec-ch-ua"] ? _parseSfBrandList(raw["sec-ch-ua"]) : null,
+    mobile:           raw["sec-ch-ua-mobile"] !== undefined ? _parseSfBoolean(raw["sec-ch-ua-mobile"]) : null,
+    platform:         raw["sec-ch-ua-platform"] !== undefined ? _parseSfString(raw["sec-ch-ua-platform"]) : null,
+    platformVersion:  raw["sec-ch-ua-platform-version"] !== undefined ? _parseSfString(raw["sec-ch-ua-platform-version"]) : null,
+    arch:             raw["sec-ch-ua-arch"] !== undefined ? _parseSfString(raw["sec-ch-ua-arch"]) : null,
+    bitness:          raw["sec-ch-ua-bitness"] !== undefined ? _parseSfString(raw["sec-ch-ua-bitness"]) : null,
+    model:            raw["sec-ch-ua-model"] !== undefined ? _parseSfString(raw["sec-ch-ua-model"]) : null,
+    fullVersionList:  raw["sec-ch-ua-full-version-list"] ? _parseSfBrandList(raw["sec-ch-ua-full-version-list"]) : null,
+    wow64:            raw["sec-ch-ua-wow64"] !== undefined ? _parseSfBoolean(raw["sec-ch-ua-wow64"]) : null,
+    formFactors:      raw["sec-ch-ua-form-factors"] ? _parseSfBrandList(raw["sec-ch-ua-form-factors"]) : null,
+    raw:              raw,
+  };
+}
+
+/**
+ * @primitive b.clientHints.acceptList
+ * @signature b.clientHints.acceptList(hintNames)
+ * @since     0.8.91
+ * @status    stable
+ * @related   b.clientHints.parse, b.clientHints.isKnownHint
+ *
+ * Build the `Accept-CH` response header value advertising which
+ * client-hint request headers the operator wants the browser to
+ * include on subsequent requests. `hintNames` is an array of
+ * canonical Sec-CH-* header names; the primitive refuses unknown
+ * hint names (typo defense — `accept-ch: Sec-CH-UA-Plateform`
+ * silently neuters the negotiation).
+ *
+ * Operators set `Accept-CH` on the HTML document response. The
+ * browser sends the listed hints on every subsequent same-origin
+ * navigation / sub-resource request.
+ *
+ * @example
+ *   res.setHeader("Accept-CH", b.clientHints.acceptList([
+ *     "Sec-CH-UA-Platform",
+ *     "Sec-CH-UA-Platform-Version",
+ *     "Sec-CH-UA-Mobile",
+ *   ]));
+ *   // → "Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-Mobile"
+ */
+function acceptList(hintNames) {
+  if (!Array.isArray(hintNames) || hintNames.length === 0) {
+    throw new ClientHintsError("client-hints/bad-hint-list",
+      "acceptList: hintNames must be a non-empty array of Sec-CH-* names");
+  }
+  var seen = {};
+  var out = [];
+  for (var i = 0; i < hintNames.length; i += 1) {
+    var n = hintNames[i];
+    if (typeof n !== "string" || n.length === 0) {
+      throw new ClientHintsError("client-hints/bad-hint-name",
+        "acceptList: hintNames[" + i + "] must be a non-empty string");
+    }
+    var canonical = KNOWN_HINTS_LC[n.toLowerCase()];
+    if (!canonical) {
+      throw new ClientHintsError("client-hints/unknown-hint",
+        "acceptList: '" + n + "' is not a known client-hint header " +
+        "(see b.clientHints.KNOWN_HINTS for the list)");
+    }
+    if (seen[canonical]) continue;
+    seen[canonical] = true;
+    out.push(canonical);
+  }
+  return out.join(", ");
+}
+
+/**
+ * @primitive b.clientHints.isKnownHint
+ * @signature b.clientHints.isKnownHint(headerName)
+ * @since     0.8.91
+ * @status    stable
+ *
+ * Returns `true` when `headerName` matches one of the well-known
+ * Sec-CH-* hint headers (case-insensitive). Operators auditing
+ * inbound headers walk the request and call this to identify
+ * negotiation-related hints without keyword-matching.
+ *
+ * @example
+ *   b.clientHints.isKnownHint("Sec-CH-UA-Mobile");    // → true
+ *   b.clientHints.isKnownHint("sec-ch-ua-platform");  // → true
+ *   b.clientHints.isKnownHint("X-Custom");            // → false
+ */
+function isKnownHint(headerName) {
+  if (typeof headerName !== "string" || headerName.length === 0) return false;
+  return Object.prototype.hasOwnProperty.call(KNOWN_HINTS_LC, headerName.toLowerCase());
+}
+
+module.exports = {
+  parse:            parse,
+  acceptList:       acceptList,
+  isKnownHint:      isKnownHint,
+  KNOWN_HINTS:      KNOWN_HINTS,
+  ClientHintsError: ClientHintsError,
+};

package/lib/vendor/blamejs/lib/cloud-events.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * @module b.cloudEvents
+ * @nav    Communication
+ * @title  CloudEvents
+ *
+ * @intro
+ *   Produce and consume webhook / pubsub / queue payloads in the
+ *   framework-neutral CNCF CloudEvents v1.0 schema
+ *   (cloudevents.io/spec/v1.0). The spec is adopted by AWS
+ *   EventBridge, Azure Event Grid, Google Eventarc, Knative, Datadog,
+ *   and the wider CNCF ecosystem — wrapping outbound events at
+ *   `b.webhook` / `b.pubsub` / `b.queue` boundaries lets operators
+ *   interop with these consumers without each consumer learning a
+ *   bespoke shape.
+ *
+ *   `wrap` produces a structured-mode envelope from operator-supplied
+ *   `source` / `type` / `subject` / `data` (and optional `extensions`),
+ *   auto-filling `id` (UUID v4) and `time` (ISO 8601). Buffer payloads
+ *   are routed to the `data_base64` field with a default
+ *   `application/octet-stream` content-type; non-Buffer payloads land
+ *   in `data` with `application/json`. `parse` validates a received
+ *   envelope against the §3.1 required-attribute set, refuses unknown
+ *   `specversion` values and the illegal `data` + `data_base64`
+ *   simultaneous form, decodes base64-mode payloads back to a Buffer,
+ *   and surfaces operator-defined extension attributes separately so
+ *   consumers can route on them without grepping the envelope.
+ *
+ *   Extension-attribute names follow the §3.1 naming rules
+ *   (lowercase ASCII alnum, 1..20 chars). Names that collide with a
+ *   spec attribute are refused.
+ *
+ * @card
+ *   Produce and consume webhook / pubsub / queue payloads in the framework-neutral CNCF CloudEvents v1.0 schema (cloudevents.io/spec/v1.0).
+ */
+
+var nodeCrypto = require("node:crypto");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var CloudEventsError = defineClass("CloudEventsError", { alwaysPermanent: true });
+
+var SPECVERSION = "1.0";
+
+// CloudEvents §3.1 — required string attributes.
+var REQUIRED_ATTRS = ["id", "source", "specversion", "type"];
+
+// CloudEvents §3.1 — known optional attributes (other strings get
+// passed through as extension attributes if they conform to the
+// naming rules).
+var KNOWN_OPTIONAL_ATTRS = {
+  datacontenttype: 1,
+  dataschema:      1,
+  subject:         1,
+  time:            1,
+  data:            1,
+  data_base64:     1,
+};
+
+// CloudEvents §3.1 attribute naming — lowercase letters + digits,
+// length 1-20.
+var EXT_ATTR_NAME_RE = /^[a-z0-9]{1,20}$/;
+
+function _isoNow() { return new Date().toISOString(); }
+
+function _genId() {
+  // RFC 4122 v4 UUID — 16 random bytes with version + variant bits.
+  return nodeCrypto.randomUUID();
+}
+
+// ---- wrap ----
+
+/**
+ * @primitive b.cloudEvents.wrap
+ * @signature b.cloudEvents.wrap(opts)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.cloudEvents.parse, b.webhook.signer, b.pubsub.create
+ *
+ * Produces a CloudEvents v1.0 structured-mode envelope from
+ * `opts.source` + `opts.type` (the only required inputs). `id` is
+ * auto-filled with a UUID v4 when absent; `time` is auto-filled with
+ * the current ISO 8601 timestamp. Buffer `data` is base64-encoded
+ * into `data_base64` with `application/octet-stream`; non-Buffer
+ * `data` lands in the `data` attribute with `application/json`.
+ * Extension keys must match `[a-z0-9]{1,20}` and must not collide
+ * with a spec attribute — both refusals throw `CloudEventsError` at
+ * config time.
+ *
+ * @opts
+ *   {
+ *     source:           string,         // required; URI-reference per §3.1
+ *     type:             string,         // required; reverse-DNS recommended
+ *     id?:              string,         // default UUID v4
+ *     time?:            string,         // default new Date().toISOString()
+ *     subject?:         string,
+ *     datacontenttype?: string,         // auto: application/json | application/octet-stream
+ *     dataschema?:      string,         // URI of payload schema
+ *     data?:            object|Buffer,  // Buffer routes to data_base64
+ *     extensions?:      object          // keys [a-z0-9]{1,20}, no spec collisions
+ *   }
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var ce = b.cloudEvents.wrap({
+ *     source:  "/services/orders",
+ *     type:    "com.example.order.created",
+ *     subject: "order/o-1234",
+ *     data:    { id: "o-1234", total: 4250 }
+ *   });
+ *   ce.specversion;
+ *   // → "1.0"
+ */
+function wrap(opts) {
+  validateOpts.requireObject(opts, "cloudEvents.wrap", CloudEventsError);
+  validateOpts.requireNonEmptyString(opts.source,
+    "cloudEvents.wrap: source", CloudEventsError, "cloud-events/bad-source");
+  validateOpts.requireNonEmptyString(opts.type,
+    "cloudEvents.wrap: type", CloudEventsError, "cloud-events/bad-type");
+  validateOpts.optionalNonEmptyString(opts.id,
+    "cloudEvents.wrap: id", CloudEventsError, "cloud-events/bad-id");
+  validateOpts.optionalNonEmptyString(opts.subject,
+    "cloudEvents.wrap: subject", CloudEventsError, "cloud-events/bad-subject");
+  validateOpts.optionalNonEmptyString(opts.time,
+    "cloudEvents.wrap: time", CloudEventsError, "cloud-events/bad-time");
+  validateOpts.optionalNonEmptyString(opts.datacontenttype,
+    "cloudEvents.wrap: datacontenttype", CloudEventsError, "cloud-events/bad-datacontenttype");
+  validateOpts.optionalNonEmptyString(opts.dataschema,
+    "cloudEvents.wrap: dataschema", CloudEventsError, "cloud-events/bad-dataschema");
+
+  var out = {
+    specversion: SPECVERSION,
+    id:          opts.id || _genId(),
+    source:      opts.source,
+    type:        opts.type,
+    time:        opts.time || _isoNow(),
+  };
+  if (opts.subject !== undefined && opts.subject !== null) out.subject = opts.subject;
+  if (opts.dataschema !== undefined && opts.dataschema !== null) out.dataschema = opts.dataschema;
+
+  // data — choose JSON vs binary based on Buffer-ness; auto-set
+  // datacontenttype when caller doesn't supply one.
+  if (opts.data !== undefined) {
+    if (Buffer.isBuffer(opts.data)) {
+      out.data_base64 = opts.data.toString("base64");
+      out.datacontenttype = opts.datacontenttype || "application/octet-stream";
+    } else {
+      out.data = opts.data;
+      out.datacontenttype = opts.datacontenttype || "application/json";
+    }
+  } else if (opts.datacontenttype) {
+    out.datacontenttype = opts.datacontenttype;
+  }
+
+  // Extension attributes — operator-defined, must conform to the
+  // §3.1 naming rules (lowercase ASCII alnum, 1-20 chars).
+  if (opts.extensions !== undefined && opts.extensions !== null) {
+    validateOpts.optionalPlainObject(opts.extensions,
+      "cloudEvents.wrap: extensions", CloudEventsError, "cloud-events/bad-extensions");
+    var extKeys = Object.keys(opts.extensions);
+    for (var i = 0; i < extKeys.length; i += 1) {
+      var k = extKeys[i];
+      // bound BEFORE regex test — k.length > 0 && k.length <= 20
+      if (typeof k !== "string" || k.length === 0 || k.length > 20 || !EXT_ATTR_NAME_RE.test(k)) {
+        throw new CloudEventsError("cloud-events/bad-extension-name",
+          "cloudEvents.wrap: extension '" + k + "' must match [a-z0-9]{1,20}");
+      }
+      if (REQUIRED_ATTRS.indexOf(k) !== -1 || KNOWN_OPTIONAL_ATTRS[k]) {
+        throw new CloudEventsError("cloud-events/extension-conflicts-with-spec",
+          "cloudEvents.wrap: extension '" + k + "' conflicts with a spec attribute");
+      }
+      out[k] = opts.extensions[k];
+    }
+  }
+  return out;
+}
+
+// ---- parse ----
+
+/**
+ * @primitive b.cloudEvents.parse
+ * @signature b.cloudEvents.parse(envelope)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.cloudEvents.wrap, b.webhook.verifier
+ *
+ * Validates a received CloudEvents v1.0 envelope and returns a
+ * normalized record `{ specversion, id, source, type, time, subject,
+ * datacontenttype, dataschema, data, extensions }`. Throws
+ * `CloudEventsError` for missing required attributes (§3.1),
+ * unsupported `specversion`, the illegal simultaneous `data` +
+ * `data_base64` form (§3.1.1), and base64-decoding failures.
+ * Buffer-mode payloads (`data_base64`) are decoded back to a
+ * `Buffer`; operator-defined extension attributes are surfaced under
+ * `.extensions` so routing can branch on them without scanning the
+ * envelope.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var record = b.cloudEvents.parse({
+ *     specversion: "1.0",
+ *     id:          "evt-1",
+ *     source:      "/services/orders",
+ *     type:        "com.example.order.created",
+ *     data:        { id: "o-1234", total: 4250 }
+ *   });
+ *   record.type;
+ *   // → "com.example.order.created"
+ */
+function parse(envelope) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    throw new CloudEventsError("cloud-events/bad-envelope",
+      "cloudEvents.parse: envelope must be a plain object");
+  }
+  for (var i = 0; i < REQUIRED_ATTRS.length; i += 1) {
+    var k = REQUIRED_ATTRS[i];
+    if (typeof envelope[k] !== "string" || envelope[k].length === 0) {
+      throw new CloudEventsError("cloud-events/missing-required",
+        "cloudEvents.parse: required attribute '" + k + "' missing or empty (CloudEvents §3.1)");
+    }
+  }
+  if (envelope.specversion !== SPECVERSION) {
+    throw new CloudEventsError("cloud-events/unsupported-specversion",
+      "cloudEvents.parse: specversion='" + envelope.specversion +
+      "' is not supported (this primitive implements CloudEvents 1.0)");
+  }
+  if (envelope.data !== undefined && envelope.data_base64 !== undefined) {
+    throw new CloudEventsError("cloud-events/data-conflict",
+      "cloudEvents.parse: envelope has both 'data' and 'data_base64' (CloudEvents §3.1.1)");
+  }
+
+  // Decode binary data if the envelope used base64 mode.
+  var decodedData = envelope.data;
+  if (envelope.data_base64 !== undefined) {
+    if (typeof envelope.data_base64 !== "string") {
+      throw new CloudEventsError("cloud-events/bad-data-base64",
+        "cloudEvents.parse: data_base64 must be a string");
+    }
+    try { decodedData = Buffer.from(envelope.data_base64, "base64"); }
+    catch (e) {
+      throw new CloudEventsError("cloud-events/bad-data-base64",
+        "cloudEvents.parse: data_base64 decode failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  // Surface extension attributes separately so consumers can route on
+  // operator-defined fields without grepping the envelope.
+  var extensions = {};
+  var keys = Object.keys(envelope);
+  for (var j = 0; j < keys.length; j += 1) {
+    var key = keys[j];
+    if (REQUIRED_ATTRS.indexOf(key) !== -1) continue;
+    if (KNOWN_OPTIONAL_ATTRS[key]) continue;
+    extensions[key] = envelope[key];
+  }
+
+  return {
+    specversion:     envelope.specversion,
+    id:              envelope.id,
+    source:          envelope.source,
+    type:            envelope.type,
+    time:            envelope.time || null,
+    subject:         envelope.subject || null,
+    datacontenttype: envelope.datacontenttype || null,
+    dataschema:      envelope.dataschema || null,
+    data:            decodedData,
+    extensions:      extensions,
+  };
+}
+
+module.exports = {
+  wrap:             wrap,
+  parse:            parse,
+  SPECVERSION:      SPECVERSION,
+  REQUIRED_ATTRS:   REQUIRED_ATTRS,
+  CloudEventsError: CloudEventsError,
+};