@blamejs/core 0.7.106 → 0.8.0

package/lib/openapi-paths-builder.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * OpenAPI 3.1 — paths / operations builder.
+ *
+ * Internal to lib/openapi.js. Holds the per-path operation table
+ * (method to operationObject) and produces the final `paths` map used
+ * by the document builder.
+ *
+ * Path keys MUST start with `/` per OpenAPI 3.1 §4.8. Path templates
+ * use `{name}` placeholders that bind to declared `parameters` of
+ * `in: path`. The builder validates that every `{name}` placeholder
+ * has a matching declared parameter at build-time.
+ *
+ * Operation methods accepted: get / put / post / delete / options /
+ * head / patch / trace (RFC 9110 + OpenAPI 3.1 §4.8.5).
+ */
+
+var validateOpts = require("./validate-opts");
+var schemaWalk   = require("./openapi-schema-walk");
+var { defineClass } = require("./framework-error");
+var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
+
+var VALID_METHODS = ["get", "put", "post", "delete",
+                     "options", "head", "patch", "trace"];
+
+// Path-template parameter extraction — each `{name}` is a path param.
+function _extractPathParams(pathTemplate) {
+  var out = [];
+  var pattern = /\{([a-zA-Z_][a-zA-Z0-9_-]*)\}/g;
+  var matched = pattern.exec(pathTemplate);
+  while (matched !== null) {
+    out.push(matched[1]);
+    matched = pattern.exec(pathTemplate);
+  }
+  return out;
+}
+
+function PathsBuilder() {
+  this._paths = {};
+}
+
+PathsBuilder.prototype.add = function (method, urlPattern, opts) {
+  opts = opts || {};
+  if (typeof method !== "string" || VALID_METHODS.indexOf(method.toLowerCase()) === -1) {
+    throw new OpenApiError("openapi/bad-method",
+      "paths.add: method must be one of " + VALID_METHODS.join(", ") +
+      " - got " + JSON.stringify(method));
+  }
+  validateOpts.requireNonEmptyString(urlPattern, "paths.add: urlPattern",
+    OpenApiError, "openapi/bad-path");
+  if (urlPattern.charAt(0) !== "/") {
+    throw new OpenApiError("openapi/bad-path",
+      "paths.add: urlPattern must start with '/' - got " +
+      JSON.stringify(urlPattern));
+  }
+  validateOpts(opts, [
+    "summary", "description", "operationId", "tags",
+    "parameters", "requestBody", "responses",
+    "security", "deprecated", "servers", "externalDocs",
+  ], "paths.add");
+
+  var op = {};
+  if (typeof opts.summary === "string")     op.summary = opts.summary;
+  if (typeof opts.description === "string") op.description = opts.description;
+  if (typeof opts.operationId === "string") op.operationId = opts.operationId;
+  if (Array.isArray(opts.tags) && opts.tags.length > 0) {
+    op.tags = opts.tags.map(function (t) {
+      if (typeof t !== "string" || t.length === 0) {
+        throw new OpenApiError("openapi/bad-tag",
+          "paths.add: tags must be non-empty strings");
+      }
+      return t;
+    });
+  }
+
+  // Parameters
+  var declaredPathParams = Object.create(null);
+  if (Array.isArray(opts.parameters)) {
+    op.parameters = [];
+    for (var i = 0; i < opts.parameters.length; i += 1) {
+      var p = _normaliseParameter(opts.parameters[i], "paths.add: parameters[" + i + "]");
+      op.parameters.push(p);
+      if (p.in === "path") declaredPathParams[p.name] = true;
+    }
+  }
+  // Verify every {placeholder} in path is declared.
+  var placeholders = _extractPathParams(urlPattern);
+  for (var j = 0; j < placeholders.length; j += 1) {
+    if (!declaredPathParams[placeholders[j]]) {
+      throw new OpenApiError("openapi/missing-path-param",
+        "paths.add: path template " + JSON.stringify(urlPattern) +
+        " references {" + placeholders[j] +
+        "} but no parameter with in=path name=" + JSON.stringify(placeholders[j]) +
+        " was declared");
+    }
+  }
+
+  // Request body
+  if (opts.requestBody) {
+    op.requestBody = _normaliseRequestBody(opts.requestBody, "paths.add: requestBody");
+  }
+
+  // Responses (required)
+  if (!opts.responses || typeof opts.responses !== "object") {
+    throw new OpenApiError("openapi/missing-responses",
+      "paths.add: responses object is required (per OpenAPI 3.1 §4.8.5)");
+  }
+  op.responses = _normaliseResponses(opts.responses, "paths.add: responses");
+
+  if (Array.isArray(opts.security)) op.security = opts.security.slice();
+  if (opts.deprecated === true)     op.deprecated = true;
+  if (Array.isArray(opts.servers))  op.servers = opts.servers.slice();
+  if (opts.externalDocs)            op.externalDocs = opts.externalDocs;
+
+  if (!this._paths[urlPattern]) this._paths[urlPattern] = {};
+  if (this._paths[urlPattern][method.toLowerCase()]) {
+    throw new OpenApiError("openapi/duplicate-operation",
+      "paths.add: duplicate operation " + method.toUpperCase() + " " + urlPattern);
+  }
+  this._paths[urlPattern][method.toLowerCase()] = op;
+  return op;
+};
+
+function _normaliseParameter(input, label) {
+  if (!input || typeof input !== "object") {
+    throw new OpenApiError("openapi/bad-parameter",
+      label + ": parameter must be an object");
+  }
+  validateOpts.requireNonEmptyString(input.name, label + ": name",
+    OpenApiError, "openapi/bad-parameter");
+  var validIn = ["path", "query", "header", "cookie"];
+  if (validIn.indexOf(input.in) === -1) {
+    throw new OpenApiError("openapi/bad-parameter",
+      label + ": in must be one of " + validIn.join(", ") +
+      " - got " + JSON.stringify(input.in));
+  }
+  if (input.in === "path" && input.required !== true) {
+    throw new OpenApiError("openapi/bad-parameter",
+      label + ": path parameter " + JSON.stringify(input.name) +
+      " must have required=true (per OpenAPI 3.1 §4.8.10)");
+  }
+  var p = {
+    name: input.name,
+    in:   input.in,
+  };
+  if (typeof input.description === "string") p.description = input.description;
+  if (input.required === true) p.required = true;
+  if (input.deprecated === true) p.deprecated = true;
+  if (input.allowEmptyValue === true) p.allowEmptyValue = true;
+  if (input.schema != null) {
+    p.schema = schemaWalk.walk(input.schema);
+  }
+  if (input.example != null) p.example = input.example;
+  return p;
+}
+
+function _normaliseRequestBody(input, label) {
+  if (!input || typeof input !== "object") {
+    throw new OpenApiError("openapi/bad-request-body",
+      label + ": requestBody must be an object");
+  }
+  if (!input.content || typeof input.content !== "object") {
+    throw new OpenApiError("openapi/bad-request-body",
+      label + ": content map required (e.g. { 'application/json': { schema: ... } })");
+  }
+  var out = { content: {} };
+  if (typeof input.description === "string") out.description = input.description;
+  if (input.required === true) out.required = true;
+  for (var ct in input.content) {
+    if (!Object.prototype.hasOwnProperty.call(input.content, ct)) continue;
+    var entry = input.content[ct];
+    if (!entry || typeof entry !== "object") {
+      throw new OpenApiError("openapi/bad-request-body",
+        label + ": content[" + JSON.stringify(ct) + "] must be an object");
+    }
+    var ce = {};
+    if (entry.schema != null) ce.schema = schemaWalk.walk(entry.schema);
+    if (entry.example != null) ce.example = entry.example;
+    if (entry.examples != null) ce.examples = entry.examples;
+    if (entry.encoding != null) ce.encoding = entry.encoding;
+    out.content[ct] = ce;
+  }
+  return out;
+}
+
+function _normaliseResponses(input, label) {
+  var out = {};
+  var statusKeys = Object.keys(input);
+  if (statusKeys.length === 0) {
+    throw new OpenApiError("openapi/missing-responses",
+      label + ": at least one response required");
+  }
+  for (var i = 0; i < statusKeys.length; i += 1) {
+    var status = statusKeys[i];
+    var resp = input[status];
+    if (!resp || typeof resp !== "object") {
+      throw new OpenApiError("openapi/bad-response",
+        label + "[" + status + "]: response must be an object");
+    }
+    var r = {};
+    if (typeof resp.description === "string") {
+      r.description = resp.description;
+    } else {
+      throw new OpenApiError("openapi/missing-response-description",
+        label + "[" + status + "]: description is required (per OpenAPI 3.1 §4.8.16)");
+    }
+    if (resp.headers != null) r.headers = resp.headers;
+    if (resp.content != null) {
+      r.content = {};
+      for (var ct in resp.content) {
+        if (!Object.prototype.hasOwnProperty.call(resp.content, ct)) continue;
+        var entry = resp.content[ct];
+        if (!entry || typeof entry !== "object") continue;
+        var ce = {};
+        if (entry.schema != null) ce.schema = schemaWalk.walk(entry.schema);
+        if (entry.example != null) ce.example = entry.example;
+        if (entry.examples != null) ce.examples = entry.examples;
+        r.content[ct] = ce;
+      }
+    }
+    if (resp.links != null) r.links = resp.links;
+    out[status] = r;
+  }
+  return out;
+}
+
+PathsBuilder.prototype.toMap = function () {
+  var sorted = Object.keys(this._paths).sort();
+  var out = {};
+  for (var i = 0; i < sorted.length; i += 1) {
+    var pathKey = sorted[i];
+    var pathItem = this._paths[pathKey];
+    var ordered = {};
+    for (var j = 0; j < VALID_METHODS.length; j += 1) {
+      var method = VALID_METHODS[j];
+      if (pathItem[method]) ordered[method] = pathItem[method];
+    }
+    out[pathKey] = ordered;
+  }
+  return out;
+};
+
+module.exports = {
+  PathsBuilder:        PathsBuilder,
+  VALID_METHODS:       VALID_METHODS,
+  _extractPathParams:  _extractPathParams,
+  OpenApiError:        OpenApiError,
+};

package/lib/openapi-schema-walk.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * OpenAPI 3.1 — converts a b.safeSchema description into the JSON
+ * Schema dialect that OpenAPI 3.1 uses (which IS JSON Schema 2020-12
+ * proper, not the OpenAPI 3.0 fork). Operators pass either:
+ *
+ *   - A b.safeSchema object (with the framework's `.parse / .optional /
+ *     ...` interface) — we walk the spec to produce JSON Schema.
+ *
+ *   - A plain JSON Schema object — passes through unchanged (just
+ *     validated for shape so a typo in the operator's hand-written
+ *     schema fails at build-time, not at consumer-time).
+ *
+ *   - A primitive type name like "string" / "integer" / "boolean" —
+ *     translated to the corresponding JSON Schema scalar.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
+
+var TYPE_KEYWORDS = ["type", "properties", "items", "enum", "const",
+                     "format", "pattern", "anyOf", "oneOf", "allOf",
+                     "not", "$ref", "$id"];
+
+function _isPlainObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function _isJsonSchemaShape(v) {
+  if (!_isPlainObject(v)) return false;
+  for (var i = 0; i < TYPE_KEYWORDS.length; i += 1) {
+    if (Object.prototype.hasOwnProperty.call(v, TYPE_KEYWORDS[i])) return true;
+  }
+  return false;
+}
+
+function _isSafeSchema(v) {
+  return !!v && typeof v === "object" &&
+         typeof v.parse === "function" && typeof v._kind === "string";
+}
+
+function _safeSchemaToJsonSchema(schema) {
+  var out  = {};
+  switch (schema._kind) {
+    case "string":
+      out.type = "string";
+      if (typeof schema._minLength === "number") out.minLength = schema._minLength;
+      if (typeof schema._maxLength === "number") out.maxLength = schema._maxLength;
+      if (schema._format)  out.format = schema._format;
+      if (schema._regex && schema._regex.source) out.pattern = schema._regex.source;
+      break;
+    case "number":
+    case "integer":
+      out.type = (schema._kind === "integer") ? "integer" : "number";
+      if (typeof schema._min === "number") out.minimum = schema._min;
+      if (typeof schema._max === "number") out.maximum = schema._max;
+      if (schema._isInt === true) out.type = "integer";
+      break;
+    case "boolean":
+      out.type = "boolean";
+      break;
+    case "literal":
+      out.const = schema._value;
+      break;
+    case "enum":
+      out.enum = (schema._values || []).slice();
+      break;
+    case "null":
+      out.type = "null";
+      break;
+    case "array":
+      out.type = "array";
+      if (schema._element != null) out.items = walk(schema._element);
+      if (typeof schema._minItems === "number") out.minItems = schema._minItems;
+      if (typeof schema._maxItems === "number") out.maxItems = schema._maxItems;
+      break;
+    case "object":
+      out.type = "object";
+      out.properties = {};
+      var requiredList = [];
+      var shape = schema.shape || schema._shape || {};
+      for (var key in shape) {
+        if (Object.prototype.hasOwnProperty.call(shape, key)) {
+          var childSchema = shape[key];
+          out.properties[key] = walk(childSchema);
+          if (!childSchema._isOptional) {
+            requiredList.push(key);
+          }
+        }
+      }
+      if (requiredList.length > 0) out.required = requiredList;
+      out.additionalProperties = (schema._mode === "passthrough") ? true : false;
+      break;
+    case "record":
+      out.type = "object";
+      if (schema._valueSchema) out.additionalProperties = walk(schema._valueSchema);
+      break;
+    case "union":
+      out.oneOf = (schema._options || []).map(walk);
+      break;
+    case "any":
+    case "unknown":
+      break;
+    default:
+      break;
+  }
+  if (schema._description) out.description = schema._description;
+  if (schema._example != null) out.example = schema._example;
+  if (schema._isNullable === true && typeof out.type === "string") {
+    out.type = [out.type, "null"];
+  }
+  return out;
+}
+
+function walk(input) {
+  if (input == null) return {};
+  if (typeof input === "string") {
+    return { type: input };
+  }
+  if (_isSafeSchema(input)) {
+    return _safeSchemaToJsonSchema(input);
+  }
+  if (_isJsonSchemaShape(input)) {
+    return _cloneJsonSchema(input);
+  }
+  if (_isPlainObject(input)) {
+    // Hand-shaped object — operator passed a JSON-Schema-like object
+    // without a recognised keyword; clone as-is and let the spec
+    // validation in build() flag it.
+    return _cloneJsonSchema(input);
+  }
+  throw new OpenApiError("openapi/bad-schema",
+    "schema-walk: unsupported schema input — got " + typeof input);
+}
+
+function _cloneJsonSchema(obj) {
+  if (obj == null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) {
+    var arrOut = [];
+    for (var i = 0; i < obj.length; i += 1) {
+      arrOut.push(_cloneJsonSchema(obj[i]));
+    }
+    return arrOut;
+  }
+  var out = {};
+  for (var key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      out[key] = _cloneJsonSchema(obj[key]);
+    }
+  }
+  return out;
+}
+
+// Validates a JSON Schema document for the most common authoring
+// errors. Used at build-time so a typo doesn't reach the spec
+// consumer. Not a full JSON-Schema-vocabulary validator — that's
+// outside scope; operators with strict needs run a downstream
+// validator like ajv against the emitted document.
+function validateJsonSchema(schema, label) {
+  validateOpts.requireNonEmptyString(label || "schema", "validateJsonSchema: label",
+    OpenApiError, "openapi/bad-schema");
+  if (!_isPlainObject(schema)) {
+    throw new OpenApiError("openapi/bad-schema",
+      label + ": schema must be a plain object");
+  }
+  if (typeof schema.type === "string") {
+    var validTypes = ["string", "number", "integer", "boolean",
+                      "object", "array", "null"];
+    if (validTypes.indexOf(schema.type) === -1) {
+      throw new OpenApiError("openapi/bad-schema",
+        label + ": invalid type " + JSON.stringify(schema.type));
+    }
+  }
+  if (Array.isArray(schema.type)) {
+    for (var i = 0; i < schema.type.length; i += 1) {
+      if (typeof schema.type[i] !== "string") {
+        throw new OpenApiError("openapi/bad-schema",
+          label + ": type[" + i + "] must be a string");
+      }
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  walk:                walk,
+  validateJsonSchema:  validateJsonSchema,
+  _isSafeSchema:       _isSafeSchema,
+  _isJsonSchemaShape:  _isJsonSchemaShape,
+  OpenApiError:        OpenApiError,
+};

package/lib/openapi-security.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * OpenAPI 3.1 — security-scheme builders.
+ *
+ * Each helper returns a JSON-Schema-compatible securityScheme object
+ * the OpenAPI builder slots under `components.securitySchemes`.
+ * Operators reference them by name in `security` requirements:
+ *
+ *   var openapi = b.openapi.create({ ... });
+ *   openapi.security.add("bearerJwt", b.openapi.security.bearer({ jwtBearer: true }));
+ *   openapi.path("get", "/me", { security: [{ bearerJwt: [] }] });
+ *
+ * Helpers cover every IANA-registered scheme operators reach for:
+ *
+ *   .bearer({ jwtBearer? })          → Bearer token
+ *   .basic()                         → HTTP Basic auth
+ *   .apiKey({ name, in })            → API key in header / query / cookie
+ *   .oauth2({ flows })               → OAuth2 with AuthCode / ClientCreds /
+ *                                       Implicit / Password flow specs
+ *   .openIdConnect({ url })          → OIDC discovery URL
+ *   .mtls()                          → mutual TLS (RFC 8705)
+ *   .dpop()                          → DPoP-bound bearer (RFC 9449)
+ *
+ * The helpers throw at config-time on bad opts (config-time-throw discipline) so
+ * an operator's typo in the OpenAPI document fails at the build step,
+ * not at consumer-validation time.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
+
+function bearer(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["jwtBearer", "description"], "openapi.security.bearer");
+  var out = {
+    type:   "http",
+    scheme: "bearer",
+  };
+  if (opts.jwtBearer === true) out.bearerFormat = "JWT";
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+function basic(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["description"], "openapi.security.basic");
+  var out = { type: "http", scheme: "basic" };
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+function apiKey(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["name", "in", "description"], "openapi.security.apiKey");
+  validateOpts.requireNonEmptyString(opts.name, "apiKey: name",
+    OpenApiError, "openapi/bad-security");
+  var validIn = ["header", "query", "cookie"];
+  if (validIn.indexOf(opts.in) === -1) {
+    throw new OpenApiError("openapi/bad-security",
+      "apiKey: in must be one of " + validIn.join(", ") +
+      " — got " + JSON.stringify(opts.in));
+  }
+  var out = { type: "apiKey", name: opts.name, in: opts.in };
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+function _validateFlow(name, flow) {
+  if (!flow || typeof flow !== "object") {
+    throw new OpenApiError("openapi/bad-security",
+      "oauth2." + name + ": flow must be an object");
+  }
+  if (typeof flow.scopes !== "object" || flow.scopes == null) {
+    throw new OpenApiError("openapi/bad-security",
+      "oauth2." + name + ": scopes must be an object (scopeName -> description)");
+  }
+  if (name === "authorizationCode" || name === "implicit") {
+    validateOpts.requireNonEmptyString(flow.authorizationUrl,
+      "oauth2." + name + ": authorizationUrl",
+      OpenApiError, "openapi/bad-security");
+  }
+  if (name === "authorizationCode" || name === "password" || name === "clientCredentials") {
+    validateOpts.requireNonEmptyString(flow.tokenUrl,
+      "oauth2." + name + ": tokenUrl",
+      OpenApiError, "openapi/bad-security");
+  }
+}
+
+function oauth2(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["flows", "description"], "openapi.security.oauth2");
+  if (!opts.flows || typeof opts.flows !== "object") {
+    throw new OpenApiError("openapi/bad-security",
+      "oauth2: flows must be an object — at least one of authorizationCode / clientCredentials / implicit / password");
+  }
+  var validFlowNames = ["authorizationCode", "clientCredentials", "implicit", "password"];
+  for (var k in opts.flows) {
+    if (!Object.prototype.hasOwnProperty.call(opts.flows, k)) continue;
+    if (validFlowNames.indexOf(k) === -1) {
+      throw new OpenApiError("openapi/bad-security",
+        "oauth2: unknown flow " + JSON.stringify(k) +
+        " — valid: " + validFlowNames.join(", "));
+    }
+    _validateFlow(k, opts.flows[k]);
+  }
+  var out = { type: "oauth2", flows: opts.flows };
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+function openIdConnect(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["url", "description"], "openapi.security.openIdConnect");
+  validateOpts.requireNonEmptyString(opts.url,
+    "openIdConnect: url", OpenApiError, "openapi/bad-security");
+  var out = { type: "openIdConnect", openIdConnectUrl: opts.url };
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+// mTLS (RFC 8705) — modeled in OpenAPI 3.1 as `mutualTLS` security
+// scheme type added in the 3.1 spec.
+function mtls(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["description"], "openapi.security.mtls");
+  var out = { type: "mutualTLS" };
+  if (typeof opts.description === "string" && opts.description.length > 0) {
+    out.description = opts.description;
+  }
+  return out;
+}
+
+// DPoP-bound bearer — emitted as a Bearer scheme with a description
+// noting the DPoP requirement; OpenAPI doesn't define a first-class
+// DPoP scheme yet.
+function dpop(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["description"], "openapi.security.dpop");
+  var desc = (typeof opts.description === "string" && opts.description.length > 0)
+    ? opts.description
+    : "Bearer token bound to a DPoP proof per RFC 9449. Client MUST send the access token in `Authorization: DPoP <token>` and the DPoP proof in the `DPoP` header.";
+  return {
+    type:        "http",
+    scheme:      "dpop",
+    description: desc,
+  };
+}
+
+module.exports = {
+  bearer:        bearer,
+  basic:         basic,
+  apiKey:        apiKey,
+  oauth2:        oauth2,
+  openIdConnect: openIdConnect,
+  mtls:          mtls,
+  dpop:          dpop,
+  OpenApiError:  OpenApiError,
+};