@blamejs/core 0.7.106 → 0.8.0

package/lib/auth/sd-jwt-vc-disclosure.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * SD-JWT VC disclosure encoding/decoding helper.
+ *
+ * Per draft-ietf-oauth-sd-jwt-vc §4.1, a disclosure is the
+ * base64url-encoded JSON serialisation of one of:
+ *
+ *   For object members:    [<salt>, <claim_name>, <claim_value>]
+ *   For array elements:    [<salt>, <array_element>]
+ *
+ * The salt is a 128-bit random value (base64url) preventing dictionary
+ * attacks on the disclosure digests. Operators that need deterministic
+ * salt for testing pass opts.saltSource.
+ */
+
+var nodeCrypto = require("node:crypto");
+var safeJson = require("../safe-json");
+var { AuthError } = require("../framework-error");
+
+var DEFAULT_SALT_BYTES = 16;          // allow:raw-byte-literal — 128-bit salt per spec recommendation
+
+function _newSalt(opts) {
+  if (opts && opts.saltSource && typeof opts.saltSource === "function") {
+    var s = opts.saltSource();
+    if (typeof s !== "string" || s.length === 0) {
+      throw new AuthError("auth-sd-jwt-vc/bad-salt",
+        "saltSource must return a non-empty string");
+    }
+    return s;
+  }
+  var bytes = nodeCrypto.randomBytes(DEFAULT_SALT_BYTES);
+  return bytes.toString("base64url");
+}
+
+function encode(claimName, claimValue, opts) {
+  if (typeof claimName !== "string" || claimName.length === 0) {
+    throw new AuthError("auth-sd-jwt-vc/bad-claim-name",
+      "encode: claimName must be a non-empty string");
+  }
+  if (claimValue === undefined) {
+    throw new AuthError("auth-sd-jwt-vc/bad-claim-value",
+      "encode: claimValue must not be undefined");
+  }
+  var salt = _newSalt(opts);
+  var arr = [salt, claimName, claimValue];
+  var jsonStr = safeJson.stringify(arr);
+  return Buffer.from(jsonStr, "utf8").toString("base64url");
+}
+
+function encodeArrayElement(elementValue, opts) {
+  if (elementValue === undefined) {
+    throw new AuthError("auth-sd-jwt-vc/bad-element-value",
+      "encodeArrayElement: elementValue must not be undefined");
+  }
+  var salt = _newSalt(opts);
+  var arr = [salt, elementValue];
+  var jsonStr = safeJson.stringify(arr);
+  return Buffer.from(jsonStr, "utf8").toString("base64url");
+}
+
+function decode(disclosureStr) {
+  if (typeof disclosureStr !== "string" || disclosureStr.length === 0) {
+    return null;
+  }
+  var jsonStr;
+  try { jsonStr = Buffer.from(disclosureStr, "base64url").toString("utf8"); }
+  catch (_e) { return null; }
+  var parsed;
+  try { parsed = safeJson.parse(jsonStr, { maxBytes: 64 * 1024 }); }                // allow:raw-byte-literal — disclosure cap (64 KB)
+  catch (_e) { return null; }
+  if (!Array.isArray(parsed)) return null;
+  if (parsed.length === 3) {
+    return {
+      salt:       parsed[0],
+      name:       parsed[1],
+      value:      parsed[2],
+      isElement:  false,
+    };
+  }
+  if (parsed.length === 2) {
+    return {
+      salt:       parsed[0],
+      value:      parsed[1],
+      isElement:  true,
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  encode:             encode,
+  encodeArrayElement: encodeArrayElement,
+  decode:             decode,
+  DEFAULT_SALT_BYTES: DEFAULT_SALT_BYTES,
+};

package/lib/auth/sd-jwt-vc-holder.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * b.auth.sdJwtVc.holder — operator-side holder/wallet helper.
+ *
+ * Wraps the lower-level present() function with key-management +
+ * stored-credential lookup + per-presentation audit emission.
+ * Operators running a wallet (mobile app backend, OIDC4VP relying
+ * party with holder role) instantiate one of these per holder.
+ *
+ *   var holder = b.auth.sdJwtVc.holder.create({
+ *     storage:       holderStorageBackend,    // operator-side persistence
+ *     holderKey:     keyPemOrJwk,
+ *     algorithm:     "ES256",
+ *     auditOn:       true,
+ *   });
+ *
+ *   // Save a credential the wallet just received from an issuer
+ *   await holder.store({
+ *     id:    "cred-1",
+ *     sdJwt: receivedFromIssuer.token,
+ *     vct:   "https://example.com/vct/identity",
+ *     issuer: "https://issuer.example.com",
+ *   });
+ *
+ *   // Build a presentation for a verifier request
+ *   var presentation = await holder.present({
+ *     credentialId:        "cred-1",
+ *     disclosedClaimNames: ["given_name"],
+ *     audience:            "https://verifier.example.com",
+ *     nonce:               nonceFromVerifier,
+ *   });
+ *
+ *   // List stored credentials
+ *   var creds = await holder.list();
+ *
+ *   // Delete a credential (on revocation / user request / DSR erasure)
+ *   await holder.delete("cred-1");
+ *
+ * Storage shape (operator implements):
+ *   { put(id, record), get(id), list(), delete(id) }
+ *
+ * The framework also ships `memoryStorage()` for development /
+ * tests — production operators wire b.db / b.objectStore.
+ */
+
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+var sdJwtVcCore = lazyRequire(function () { return require("./sd-jwt-vc"); });
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _validateStorage(storage) {
+  if (!storage || typeof storage !== "object") return false;
+  return ["put", "get", "list", "delete"].every(function (m) {
+    return typeof storage[m] === "function";
+  });
+}
+
+function memoryStorage() {
+  var byId = new Map();
+  return {
+    put: async function (id, record) {
+      byId.set(id, Object.assign({}, record, { id: id }));
+    },
+    get: async function (id) {
+      var r = byId.get(id);
+      return r ? Object.assign({}, r) : null;
+    },
+    list: async function () {
+      return Array.from(byId.values()).map(function (r) {
+        return Object.assign({}, r);
+      });
+    },
+    delete: async function (id) {
+      var existed = byId.has(id);
+      byId.delete(id);
+      return existed;
+    },
+    _size: function () { return byId.size; },
+  };
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "auth.sdJwtVc.holder.create", AuthError);
+  validateOpts(opts, [
+    "storage", "holderKey", "algorithm", "auditOn",
+  ], "auth.sdJwtVc.holder.create");
+
+  if (!_validateStorage(opts.storage)) {
+    throw new AuthError("auth-sd-jwt-vc/bad-storage",
+      "holder.create: storage must implement { put, get, list, delete }");
+  }
+  if (!opts.holderKey) {
+    throw new AuthError("auth-sd-jwt-vc/no-key",
+      "holder.create: holderKey required");
+  }
+  var algorithm = opts.algorithm || "ES256";
+  var auditOn = opts.auditOn !== false;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _emitMetric(verb) {
+    try { observability().safeEvent("auth.sdJwtVc.holder." + verb, 1, {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  async function store(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new AuthError("auth-sd-jwt-vc/bad-spec",
+        "holder.store: spec must be an object");
+    }
+    if (typeof spec.id !== "string" || spec.id.length === 0) {
+      throw new AuthError("auth-sd-jwt-vc/bad-id",
+        "holder.store: id is required");
+    }
+    if (typeof spec.sdJwt !== "string") {
+      throw new AuthError("auth-sd-jwt-vc/bad-token",
+        "holder.store: sdJwt is required");
+    }
+    var record = {
+      id:        spec.id,
+      sdJwt:     spec.sdJwt,
+      vct:       spec.vct || null,
+      issuer:    spec.issuer || null,
+      receivedAt: Date.now(),
+    };
+    await opts.storage.put(spec.id, record);
+    _emitAudit("auth.sdJwtVc.holder.stored", "success", {
+      id: spec.id, vct: record.vct, issuer: record.issuer,
+    });
+    _emitMetric("stored");
+    return record;
+  }
+
+  async function present(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new AuthError("auth-sd-jwt-vc/bad-spec",
+        "holder.present: spec must be an object");
+    }
+    var record = await opts.storage.get(spec.credentialId);
+    if (!record) {
+      throw new AuthError("auth-sd-jwt-vc/credential-not-found",
+        "holder.present: credentialId \"" + spec.credentialId + "\" not found in storage");
+    }
+    var presentation = sdJwtVcCore().present({
+      sdJwt:               record.sdJwt,
+      disclosedClaimNames: spec.disclosedClaimNames || [],
+      audience:            spec.audience || null,
+      nonce:               spec.nonce || null,
+      holderKey:           opts.holderKey,
+      algorithm:           algorithm,
+    });
+    _emitAudit("auth.sdJwtVc.holder.presented", "success", {
+      credentialId: spec.credentialId,
+      audience:     spec.audience || null,
+      disclosed:    (spec.disclosedClaimNames || []).length,
+    });
+    _emitMetric("presented");
+    return presentation;
+  }
+
+  async function list() {
+    var rows = await opts.storage.list();
+    return Array.isArray(rows) ? rows : [];
+  }
+
+  async function get(id) {
+    return await opts.storage.get(id);
+  }
+
+  async function _delete(id) {
+    var existed = await opts.storage.delete(id);
+    if (existed) {
+      _emitAudit("auth.sdJwtVc.holder.deleted", "success", { id: id });
+      _emitMetric("deleted");
+    }
+    return existed;
+  }
+
+  return {
+    store:    store,
+    present:  present,
+    list:     list,
+    get:      get,
+    delete:   _delete,
+  };
+}
+
+module.exports = {
+  create:        create,
+  memoryStorage: memoryStorage,
+};

package/lib/auth/sd-jwt-vc-issuer.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * b.auth.sdJwtVc.issuer — operator-side SD-JWT VC issuer factory.
+ *
+ * Wraps the lower-level issue() function with key-management + key-id
+ * (kid) + per-issuance audit emission. Operators running an issuer
+ * service (EUDI Wallet provider, OIDC4VCI issuer, internal credential
+ * service) instantiate one of these per signing key.
+ *
+ *   var issuer = b.auth.sdJwtVc.issuer.create({
+ *     issuerUrl:    "https://issuer.example.com",
+ *     keys: [
+ *       { kid: "issuer-2026-q2", privateKey: pem, algorithm: "ES256" },
+ *     ],
+ *     activeKid:    "issuer-2026-q2",
+ *     defaultTtlMs: C.TIME.days(90),
+ *     auditOn:      true,
+ *   });
+ *
+ *   var sdJwt = await issuer.issue({
+ *     vct:           "https://example.com/vct/identity",
+ *     subject:       "did:web:alice",
+ *     claims: {
+ *       given_name:    "Alice",
+ *       family_name:   "Smith",
+ *       birthdate:     "1990-01-15",
+ *     },
+ *     selectivelyDisclosed: ["given_name", "family_name", "birthdate"],
+ *     holderKey:     holderJwk,
+ *   });
+ *
+ *   // Key rollover (rotate to a new signing key)
+ *   issuer.rotateKey({ kid: "issuer-2026-q3", privateKey: pem2 });
+ *
+ *   // Operator-side audit / metering
+ *   var stats = issuer.stats();   // { issued, lastIssuedAt, keys: [...] }
+ *
+ * Audit emissions (audit namespace `auth`):
+ *   auth.sdJwtVc.issued        — every successful issue() call
+ *   auth.sdJwtVc.key_rotated   — every rotateKey() invocation
+ */
+
+var C = require("../constants");
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+// Lazy-required to avoid the issuer ↔ core circular load: sd-jwt-vc.js
+// requires sd-jwt-vc-issuer.js for its module.exports surface, and
+// the issuer needs sd-jwt-vc.js's issue() function for the actual
+// signing path.
+var sdJwtVcCore = lazyRequire(function () { return require("./sd-jwt-vc"); });
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function create(opts) {
+  validateOpts.requireObject(opts, "auth.sdJwtVc.issuer.create", AuthError);
+  validateOpts(opts, [
+    "issuerUrl", "keys", "activeKid",
+    "defaultTtlMs", "defaultHashAlg", "auditOn",
+  ], "auth.sdJwtVc.issuer.create");
+
+  validateOpts.requireNonEmptyString(opts.issuerUrl,
+    "issuer.create: issuerUrl", AuthError, "auth-sd-jwt-vc/bad-opts");
+  if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
+    throw new AuthError("auth-sd-jwt-vc/no-keys",
+      "issuer.create: keys must be a non-empty array");
+  }
+  for (var i = 0; i < opts.keys.length; i++) {
+    var k = opts.keys[i];
+    if (!k || typeof k !== "object") {
+      throw new AuthError("auth-sd-jwt-vc/bad-key",
+        "issuer.create: keys[" + i + "] must be an object");
+    }
+    if (typeof k.kid !== "string" || k.kid.length === 0) {
+      throw new AuthError("auth-sd-jwt-vc/bad-key",
+        "issuer.create: keys[" + i + "].kid is required");
+    }
+    if (!k.privateKey) {
+      throw new AuthError("auth-sd-jwt-vc/bad-key",
+        "issuer.create: keys[" + i + "].privateKey is required");
+    }
+  }
+  validateOpts.optionalPositiveFinite(opts.defaultTtlMs,
+    "issuer.create: defaultTtlMs", AuthError, "auth-sd-jwt-vc/bad-opts");
+
+  var keysByKid = Object.create(null);
+  for (var j = 0; j < opts.keys.length; j++) {
+    keysByKid[opts.keys[j].kid] = opts.keys[j];
+  }
+  var activeKid = opts.activeKid || opts.keys[0].kid;
+  if (!keysByKid[activeKid]) {
+    throw new AuthError("auth-sd-jwt-vc/bad-active-kid",
+      "issuer.create: activeKid \"" + activeKid + "\" is not in the keys array");
+  }
+  var defaultTtlMs = opts.defaultTtlMs || C.TIME.days(90);
+  var defaultHashAlg = opts.defaultHashAlg || "sha-256";
+  var auditOn = opts.auditOn !== false;
+
+  var stats = {
+    issued:       0,
+    lastIssuedAt: null,
+    keysRotated:  0,
+  };
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _emitMetric(verb) {
+    try { observability().safeEvent("auth.sdJwtVc.issuer." + verb, 1, {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  async function issue(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new AuthError("auth-sd-jwt-vc/bad-spec",
+        "issuer.issue: spec must be an object");
+    }
+    if (typeof spec.vct !== "string") {
+      throw new AuthError("auth-sd-jwt-vc/bad-spec",
+        "issuer.issue: vct is required");
+    }
+    var key = keysByKid[activeKid];
+    var issued = sdJwtVcCore().issue({
+      issuer:               opts.issuerUrl,
+      subject:              spec.subject || null,
+      vct:                  spec.vct,
+      claims:               spec.claims || {},
+      selectivelyDisclosed: spec.selectivelyDisclosed || [],
+      issuerKey:            key.privateKey,
+      algorithm:            key.algorithm || "ES256",
+      hashAlg:              spec.hashAlg || defaultHashAlg,
+      ttlMs:                spec.ttlMs || defaultTtlMs,
+      holderKey:            spec.holderKey || null,
+      issuedAt:             spec.issuedAt,
+      extraHeader:          { kid: activeKid },
+    });
+    stats.issued += 1;
+    stats.lastIssuedAt = Date.now();
+    _emitAudit("auth.sdJwtVc.issued", "success", {
+      kid:       activeKid,
+      vct:       spec.vct,
+      subject:   spec.subject || null,
+      disclosed: (spec.selectivelyDisclosed || []).length,
+    });
+    _emitMetric("issued");
+    return issued;
+  }
+
+  function rotateKey(newKey) {
+    if (!newKey || typeof newKey !== "object" ||
+        typeof newKey.kid !== "string" || !newKey.privateKey) {
+      throw new AuthError("auth-sd-jwt-vc/bad-key",
+        "rotateKey: must pass { kid, privateKey, algorithm? }");
+    }
+    keysByKid[newKey.kid] = newKey;
+    activeKid = newKey.kid;
+    stats.keysRotated += 1;
+    _emitAudit("auth.sdJwtVc.key_rotated", "success", {
+      newKid: newKey.kid,
+    });
+    _emitMetric("key_rotated");
+  }
+
+  function listKids() { return Object.keys(keysByKid); }
+
+  function statsSnapshot() {
+    return {
+      issued:       stats.issued,
+      lastIssuedAt: stats.lastIssuedAt,
+      keysRotated:  stats.keysRotated,
+      activeKid:    activeKid,
+      kids:         listKids(),
+    };
+  }
+
+  return {
+    issue:      issue,
+    rotateKey:  rotateKey,
+    listKids:   listKids,
+    stats:      statsSnapshot,
+    issuerUrl:  opts.issuerUrl,
+  };
+}
+
+module.exports = {
+  create: create,
+};