@astrasyncai/verification-gateway 5.18.0 → 5.19.0

package/dist/adapters/http-pdlss.d.mts

@@ -77,5 +77,11 @@ declare function normalizePurposeHeader(value: string): {
  * outranks agent-supplied headers the way MCP toolGates do.
  */
 declare function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution;
+/**
+ * 5.19.0 — the coarse purpose source sent to verify-access as
+ * `purposeSource`. Only `'route_config'` changes server behaviour (checked
+ * against the endpoint's stored rules); the rest are attribution.
+ */
+declare function wirePurposeSource(source: HttpPurposeSource): 'route_config' | 'header' | 'body' | 'default';
 
-export { DEFAULT_HTTP_ACTION, DEFAULT_HTTP_PURPOSE, HTTP_METHOD_ACTION_TABLE, type HttpActionSource, type HttpPdlssInput, type HttpPdlssResolution, type HttpPurposeSource, actionForHttpMethod, normalizePurposeHeader, resolveHttpPdlss };
+export { DEFAULT_HTTP_ACTION, DEFAULT_HTTP_PURPOSE, HTTP_METHOD_ACTION_TABLE, type HttpActionSource, type HttpPdlssInput, type HttpPdlssResolution, type HttpPurposeSource, actionForHttpMethod, normalizePurposeHeader, resolveHttpPdlss, wirePurposeSource };

package/dist/adapters/http-pdlss.d.ts

@@ -77,5 +77,11 @@ declare function normalizePurposeHeader(value: string): {
  * outranks agent-supplied headers the way MCP toolGates do.
  */
 declare function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution;
+/**
+ * 5.19.0 — the coarse purpose source sent to verify-access as
+ * `purposeSource`. Only `'route_config'` changes server behaviour (checked
+ * against the endpoint's stored rules); the rest are attribution.
+ */
+declare function wirePurposeSource(source: HttpPurposeSource): 'route_config' | 'header' | 'body' | 'default';
 
-export { DEFAULT_HTTP_ACTION, DEFAULT_HTTP_PURPOSE, HTTP_METHOD_ACTION_TABLE, type HttpActionSource, type HttpPdlssInput, type HttpPdlssResolution, type HttpPurposeSource, actionForHttpMethod, normalizePurposeHeader, resolveHttpPdlss };
+export { DEFAULT_HTTP_ACTION, DEFAULT_HTTP_PURPOSE, HTTP_METHOD_ACTION_TABLE, type HttpActionSource, type HttpPdlssInput, type HttpPdlssResolution, type HttpPurposeSource, actionForHttpMethod, normalizePurposeHeader, resolveHttpPdlss, wirePurposeSource };

package/dist/adapters/http-pdlss.js

@@ -25,7 +25,8 @@ __export(http_pdlss_exports, {
   HTTP_METHOD_ACTION_TABLE: () => HTTP_METHOD_ACTION_TABLE,
   actionForHttpMethod: () => actionForHttpMethod,
   normalizePurposeHeader: () => normalizePurposeHeader,
-  resolveHttpPdlss: () => resolveHttpPdlss
+  resolveHttpPdlss: () => resolveHttpPdlss,
+  wirePurposeSource: () => wirePurposeSource
 });
 module.exports = __toCommonJS(http_pdlss_exports);
 var HTTP_METHOD_ACTION_TABLE = {
@@ -105,6 +106,20 @@ function resolveHttpPdlss(input) {
   }
   return { purpose, action, purposeSource, actionSource };
 }
+function wirePurposeSource(source) {
+  switch (source) {
+    case "route_config":
+      return "route_config";
+    case "header":
+    case "legacy_header":
+    case "query":
+      return "header";
+    case "custom_extractor":
+      return "body";
+    default:
+      return "default";
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_HTTP_ACTION,
@@ -112,6 +127,7 @@ function resolveHttpPdlss(input) {
   HTTP_METHOD_ACTION_TABLE,
   actionForHttpMethod,
   normalizePurposeHeader,
-  resolveHttpPdlss
+  resolveHttpPdlss,
+  wirePurposeSource
 });
 //# sourceMappingURL=http-pdlss.js.map

package/dist/adapters/http-pdlss.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}
+{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n\n/**\n * 5.19.0 — the coarse purpose source sent to verify-access as\n * `purposeSource`. Only `'route_config'` changes server behaviour (checked\n * against the endpoint's stored rules); the rest are attribution.\n */\nexport function wirePurposeSource(\n  source: HttpPurposeSource\n): 'route_config' | 'header' | 'body' | 'default' {\n  switch (source) {\n    case 'route_config':\n      return 'route_config';\n    case 'header':\n    case 'legacy_header':\n    case 'query':\n      return 'header';\n    case 'custom_extractor':\n      return 'body';\n    default:\n      return 'default';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;AAOO,SAAS,kBACd,QACgD;AAChD,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;","names":[]}

package/dist/adapters/http-pdlss.mjs

@@ -76,12 +76,27 @@ function resolveHttpPdlss(input) {
   }
   return { purpose, action, purposeSource, actionSource };
 }
+function wirePurposeSource(source) {
+  switch (source) {
+    case "route_config":
+      return "route_config";
+    case "header":
+    case "legacy_header":
+    case "query":
+      return "header";
+    case "custom_extractor":
+      return "body";
+    default:
+      return "default";
+  }
+}
 export {
   DEFAULT_HTTP_ACTION,
   DEFAULT_HTTP_PURPOSE,
   HTTP_METHOD_ACTION_TABLE,
   actionForHttpMethod,
   normalizePurposeHeader,
-  resolveHttpPdlss
+  resolveHttpPdlss,
+  wirePurposeSource
 };
 //# sourceMappingURL=http-pdlss.mjs.map

package/dist/adapters/http-pdlss.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}
+{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n\n/**\n * 5.19.0 — the coarse purpose source sent to verify-access as\n * `purposeSource`. Only `'route_config'` changes server behaviour (checked\n * against the endpoint's stored rules); the rest are attribution.\n */\nexport function wirePurposeSource(\n  source: HttpPurposeSource\n): 'route_config' | 'header' | 'body' | 'default' {\n  switch (source) {\n    case 'route_config':\n      return 'route_config';\n    case 'header':\n    case 'legacy_header':\n    case 'query':\n      return 'header';\n    case 'custom_extractor':\n      return 'body';\n    default:\n      return 'default';\n  }\n}\n"],"mappings":";AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;AAOO,SAAS,kBACd,QACgD;AAChD,UAAQ,QAAQ;AAAA,IACd,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;","names":[]}

package/dist/adapters/kit-express.d.mts

@@ -7,6 +7,49 @@ interface KitRequestContext {
      */
     callerId?: string;
 }
+/**
+ * 5.19.0: what an approval-event resume did. `terminal` outcomes are final
+ * for the event (the dispatcher answers 2xx and marks the event seen);
+ * non-terminal ones (`busy`, `still_held`) answer 5xx so the platform
+ * retries.
+ */
+type ResumeOutcome = 'completed' | 'pending' | 'payment_failed' | 'cart_invalid' | 'not_authorized' | 'declined' | 'already_completed' | 'canceled' | 'not_held' | 'stale' | 'not_found' | 'busy' | 'still_held';
+interface ResumeResult<S> {
+    outcome: ResumeOutcome;
+    terminal: boolean;
+    session: S | null;
+}
+/** 5.19.0: the approval event AstraSync POSTs to your endpoint's Events URL. */
+interface ApprovalEvent {
+    /** Stable across retries — dedupe on it. */
+    eventId: string;
+    type: 'step_up.approved' | 'step_up.denied' | 'step_up.expired' | 'step_up.lapsed';
+    approvalId: string;
+    /** The cart id the confirm carried (the platform's, else the kit's session id). */
+    checkoutSessionId: string;
+    /** The kit session id the confirm carried in `metadata`. */
+    kitSessionId?: string;
+    protocol?: 'ucp' | 'acp';
+    counterpartyId: string;
+    agentAstraId: string;
+    transactionValue: number;
+    currency: string;
+    decidedAt: string;
+    /** Approved only: the approval can be redeemed until this instant (ISO). */
+    redeemBy?: string;
+}
+/** A kit the approval-event dispatcher can route to (both checkout kits). */
+interface ApprovalEventKit {
+    readonly protocol: 'ucp' | 'acp';
+    /** Apply one verified event to the kit session it names. */
+    applyApprovalEvent(event: ApprovalEvent): Promise<ResumeResult<unknown>>;
+}
+
+/** Where the dispatcher remembers events it finished (dedupe). */
+interface SeenEvents {
+    has(eventId: string): Promise<boolean>;
+    add(eventId: string): Promise<void>;
+}
 
 /**
  * 5.18.0 — mount a fetch-style checkout kit (`createUcpCheckoutKit`,
@@ -24,11 +67,28 @@ interface KitRequestContext {
  * When the AstraSync middleware ran first, the caller's verified ASTRA-id
  * (`req.agentVerification.agent.astraId`) scopes sessions and idempotency
  * keys; override with `callerId`.
+ *
+ * 5.19.0:
+ * - the request URL the kit sees uses the kit's `publicOrigin` (UCP default:
+ *   the origin of `profile.endpoint`), so RFC 9421 `@target-uri` /
+ *   `@authority` and the forwarded agent artifacts match what the agent
+ *   signed behind a TLS-terminating proxy. Without one (ACP default), the
+ *   origin is `X-Forwarded-Proto` / `X-Forwarded-Host` when Express
+ *   `trust proxy` is set, else `req.protocol` + Host.
+ * - `approvalEventsPath` + `webhookSecret` mount the owner-approval events
+ *   receiver on the same handler (`handleApprovalEvents`); or mount
+ *   `approvalEventsHandler({ secret, kits: [ucpKit, acpKit] })` on its own
+ *   path to serve both kits from one Events URL.
  */
 
 /** Anything with a fetch-style `handle` (both checkout kits). */
 interface FetchKit {
     handle(req: Request, ctx?: KitRequestContext): Promise<Response>;
+    /** 5.19.0: the public origin to rebuild request URLs with (both kits expose it). */
+    readonly publicOrigin?: string;
+    /** 5.19.0: present on both kits — makes the kit an approval-event target. */
+    readonly protocol?: 'ucp' | 'acp';
+    applyApprovalEvent?: ApprovalEventKit['applyApprovalEvent'];
 }
 /** The parts of an Express request this adapter reads. */
 interface KitExpressRequest {
@@ -40,6 +100,10 @@ interface KitExpressRequest {
     body?: unknown;
     rawBody?: unknown;
     get?(name: string): string | undefined;
+    /** Express app (to read the `trust proxy` setting). */
+    app?: {
+        get(name: string): unknown;
+    };
     agentVerification?: {
         identityVerified?: boolean;
         agent?: {
@@ -56,8 +120,36 @@ interface KitExpressResponse {
 interface ExpressHandlerOptions {
     /** The caller's verified ASTRA-id (default: from `req.agentVerification` when identity-verified). */
     callerId?: (req: KitExpressRequest) => string | undefined;
+    /**
+     * 5.19.0: serve owner-approval events on this path (POST; matched against
+     * the full request path or the path under the mount point), e.g.
+     * `'/astrasync/events'`. Set the endpoint's Events URL to it. Needs
+     * `webhookSecret`.
+     */
+    approvalEventsPath?: string;
+    /** 5.19.0: the endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    webhookSecret?: string | readonly string[];
+    /** 5.19.0: the kits events may name (default: this kit). */
+    approvalEventKits?: ApprovalEventKit[];
+    /** 5.19.0: dedupe store for event ids (default: process-local memory). */
+    seenEvents?: SeenEvents | ((eventId: string) => Promise<boolean>);
 }
+interface ApprovalEventsHandlerOptions {
+    /** The endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    secret: string | readonly string[];
+    /** The kits events may name, e.g. `[ucpKit, acpKit]`. */
+    kits: ApprovalEventKit[];
+    /** Dedupe store (default: process-local memory). */
+    seen?: SeenEvents | ((eventId: string) => Promise<boolean>);
+}
+/**
+ * 5.19.0: an Express handler for the endpoint's Events URL, serving both
+ * kits: `app.post('/astrasync/events', express.raw({ type: '*\/*' }),
+ * approvalEventsHandler({ secret, kits: [ucpKit, acpKit] }))`. Answers 2xx
+ * when done, 401 on a bad signature, 503 to have the platform retry.
+ */
+declare function approvalEventsHandler(options: ApprovalEventsHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 /** An Express handler that runs a checkout kit and writes its Response back. */
 declare function expressHandler(kit: FetchKit, options?: ExpressHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 
-export { type ExpressHandlerOptions, type FetchKit, type KitExpressRequest, type KitExpressResponse, expressHandler };
+export { type ApprovalEventsHandlerOptions, type ExpressHandlerOptions, type FetchKit, type KitExpressRequest, type KitExpressResponse, approvalEventsHandler, expressHandler };

package/dist/adapters/kit-express.d.ts

@@ -7,6 +7,49 @@ interface KitRequestContext {
      */
     callerId?: string;
 }
+/**
+ * 5.19.0: what an approval-event resume did. `terminal` outcomes are final
+ * for the event (the dispatcher answers 2xx and marks the event seen);
+ * non-terminal ones (`busy`, `still_held`) answer 5xx so the platform
+ * retries.
+ */
+type ResumeOutcome = 'completed' | 'pending' | 'payment_failed' | 'cart_invalid' | 'not_authorized' | 'declined' | 'already_completed' | 'canceled' | 'not_held' | 'stale' | 'not_found' | 'busy' | 'still_held';
+interface ResumeResult<S> {
+    outcome: ResumeOutcome;
+    terminal: boolean;
+    session: S | null;
+}
+/** 5.19.0: the approval event AstraSync POSTs to your endpoint's Events URL. */
+interface ApprovalEvent {
+    /** Stable across retries — dedupe on it. */
+    eventId: string;
+    type: 'step_up.approved' | 'step_up.denied' | 'step_up.expired' | 'step_up.lapsed';
+    approvalId: string;
+    /** The cart id the confirm carried (the platform's, else the kit's session id). */
+    checkoutSessionId: string;
+    /** The kit session id the confirm carried in `metadata`. */
+    kitSessionId?: string;
+    protocol?: 'ucp' | 'acp';
+    counterpartyId: string;
+    agentAstraId: string;
+    transactionValue: number;
+    currency: string;
+    decidedAt: string;
+    /** Approved only: the approval can be redeemed until this instant (ISO). */
+    redeemBy?: string;
+}
+/** A kit the approval-event dispatcher can route to (both checkout kits). */
+interface ApprovalEventKit {
+    readonly protocol: 'ucp' | 'acp';
+    /** Apply one verified event to the kit session it names. */
+    applyApprovalEvent(event: ApprovalEvent): Promise<ResumeResult<unknown>>;
+}
+
+/** Where the dispatcher remembers events it finished (dedupe). */
+interface SeenEvents {
+    has(eventId: string): Promise<boolean>;
+    add(eventId: string): Promise<void>;
+}
 
 /**
  * 5.18.0 — mount a fetch-style checkout kit (`createUcpCheckoutKit`,
@@ -24,11 +67,28 @@ interface KitRequestContext {
  * When the AstraSync middleware ran first, the caller's verified ASTRA-id
  * (`req.agentVerification.agent.astraId`) scopes sessions and idempotency
  * keys; override with `callerId`.
+ *
+ * 5.19.0:
+ * - the request URL the kit sees uses the kit's `publicOrigin` (UCP default:
+ *   the origin of `profile.endpoint`), so RFC 9421 `@target-uri` /
+ *   `@authority` and the forwarded agent artifacts match what the agent
+ *   signed behind a TLS-terminating proxy. Without one (ACP default), the
+ *   origin is `X-Forwarded-Proto` / `X-Forwarded-Host` when Express
+ *   `trust proxy` is set, else `req.protocol` + Host.
+ * - `approvalEventsPath` + `webhookSecret` mount the owner-approval events
+ *   receiver on the same handler (`handleApprovalEvents`); or mount
+ *   `approvalEventsHandler({ secret, kits: [ucpKit, acpKit] })` on its own
+ *   path to serve both kits from one Events URL.
  */
 
 /** Anything with a fetch-style `handle` (both checkout kits). */
 interface FetchKit {
     handle(req: Request, ctx?: KitRequestContext): Promise<Response>;
+    /** 5.19.0: the public origin to rebuild request URLs with (both kits expose it). */
+    readonly publicOrigin?: string;
+    /** 5.19.0: present on both kits — makes the kit an approval-event target. */
+    readonly protocol?: 'ucp' | 'acp';
+    applyApprovalEvent?: ApprovalEventKit['applyApprovalEvent'];
 }
 /** The parts of an Express request this adapter reads. */
 interface KitExpressRequest {
@@ -40,6 +100,10 @@ interface KitExpressRequest {
     body?: unknown;
     rawBody?: unknown;
     get?(name: string): string | undefined;
+    /** Express app (to read the `trust proxy` setting). */
+    app?: {
+        get(name: string): unknown;
+    };
     agentVerification?: {
         identityVerified?: boolean;
         agent?: {
@@ -56,8 +120,36 @@ interface KitExpressResponse {
 interface ExpressHandlerOptions {
     /** The caller's verified ASTRA-id (default: from `req.agentVerification` when identity-verified). */
     callerId?: (req: KitExpressRequest) => string | undefined;
+    /**
+     * 5.19.0: serve owner-approval events on this path (POST; matched against
+     * the full request path or the path under the mount point), e.g.
+     * `'/astrasync/events'`. Set the endpoint's Events URL to it. Needs
+     * `webhookSecret`.
+     */
+    approvalEventsPath?: string;
+    /** 5.19.0: the endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    webhookSecret?: string | readonly string[];
+    /** 5.19.0: the kits events may name (default: this kit). */
+    approvalEventKits?: ApprovalEventKit[];
+    /** 5.19.0: dedupe store for event ids (default: process-local memory). */
+    seenEvents?: SeenEvents | ((eventId: string) => Promise<boolean>);
 }
+interface ApprovalEventsHandlerOptions {
+    /** The endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    secret: string | readonly string[];
+    /** The kits events may name, e.g. `[ucpKit, acpKit]`. */
+    kits: ApprovalEventKit[];
+    /** Dedupe store (default: process-local memory). */
+    seen?: SeenEvents | ((eventId: string) => Promise<boolean>);
+}
+/**
+ * 5.19.0: an Express handler for the endpoint's Events URL, serving both
+ * kits: `app.post('/astrasync/events', express.raw({ type: '*\/*' }),
+ * approvalEventsHandler({ secret, kits: [ucpKit, acpKit] }))`. Answers 2xx
+ * when done, 401 on a bad signature, 503 to have the platform retry.
+ */
+declare function approvalEventsHandler(options: ApprovalEventsHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 /** An Express handler that runs a checkout kit and writes its Response back. */
 declare function expressHandler(kit: FetchKit, options?: ExpressHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 
-export { type ExpressHandlerOptions, type FetchKit, type KitExpressRequest, type KitExpressResponse, expressHandler };
+export { type ApprovalEventsHandlerOptions, type ExpressHandlerOptions, type FetchKit, type KitExpressRequest, type KitExpressResponse, approvalEventsHandler, expressHandler };

package/dist/adapters/kit-express.js

@@ -20,10 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/adapters/kit-express.ts
 var kit_express_exports = {};
 __export(kit_express_exports, {
+  approvalEventsHandler: () => approvalEventsHandler,
   expressHandler: () => expressHandler
 });
 module.exports = __toCommonJS(kit_express_exports);
 
+// src/http-signatures/sign.ts
+var import_http_message_signatures = require("http-message-signatures");
+
 // src/ucp/kit-shared.ts
 var warned = /* @__PURE__ */ new Set();
 function warnOnce(key, message) {
@@ -32,6 +36,145 @@ function warnOnce(key, message) {
   console.warn(message);
 }
 
+// src/webhooks.ts
+var import_crypto = require("crypto");
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(header) {
+  let t;
+  const signatures = [];
+  for (const segment of header.split(",")) {
+    const eq = segment.indexOf("=");
+    if (eq < 0) continue;
+    const k = segment.slice(0, eq).trim();
+    const v = segment.slice(eq + 1).trim();
+    if (k === "t") t = v;
+    else if ((k === "v1" || k === "v1old") && v) signatures.push(v);
+  }
+  return { t, signatures };
+}
+function computeHmac(secret, signedPayload) {
+  return (0, import_crypto.createHmac)("sha256", secret).update(signedPayload, "utf8").digest("hex");
+}
+function constantTimeEquals(a, b) {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return (0, import_crypto.timingSafeEqual)(aBuf, bBuf);
+}
+function verifyAstraSyncWebhook(rawBody, headers, secret, options = {}) {
+  const secrets = (Array.isArray(secret) ? secret : [secret]).filter(
+    (x) => typeof x === "string" && x.length > 0
+  );
+  if (!secrets.length) return { ok: false, reason: "no_secret_provided" };
+  const rawHeader = headers["x-astrasync-signature"] ?? headers["X-Astrasync-Signature"] ?? headers["X-AstraSync-Signature"] ?? headers["X-ASTRASYNC-SIGNATURE"];
+  if (!rawHeader) return { ok: false, reason: "missing_signature_header" };
+  const headerValue = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+  const { t: timestamp, signatures } = parseSignatureHeader(headerValue);
+  if (!timestamp || !signatures.length) {
+    return { ok: false, reason: "malformed_signature_header" };
+  }
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  const now = options.nowMs ?? Date.now();
+  const tsSeconds = Number(timestamp);
+  if (!Number.isFinite(tsSeconds)) {
+    return { ok: false, reason: "invalid_timestamp" };
+  }
+  const ageSeconds = Math.abs(now / 1e3 - tsSeconds);
+  if (ageSeconds > tolerance) {
+    return { ok: false, reason: "timestamp_outside_tolerance" };
+  }
+  for (const key of secrets) {
+    const expectedSignature = computeHmac(key, `${timestamp}.${rawBody}`);
+    if (signatures.some((received) => constantTimeEquals(expectedSignature, received))) {
+      return { ok: true };
+    }
+  }
+  return { ok: false, reason: "signature_mismatch" };
+}
+
+// src/ucp/approval-events.ts
+var MemorySeenEvents = class {
+  constructor(max = 1e4) {
+    this.max = max;
+    this.ids = /* @__PURE__ */ new Set();
+  }
+  async has(eventId) {
+    return this.ids.has(eventId);
+  }
+  async add(eventId) {
+    if (this.ids.size >= this.max) {
+      const first2 = this.ids.values().next().value;
+      if (first2 !== void 0) this.ids.delete(first2);
+    }
+    this.ids.add(eventId);
+  }
+};
+var defaultSeen = new MemorySeenEvents();
+var TYPES = /* @__PURE__ */ new Set(["step_up.approved", "step_up.denied", "step_up.expired", "step_up.lapsed"]);
+function toHeaderRecord(headers) {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    const out2 = {};
+    headers.forEach((v, k) => out2[k.toLowerCase()] = v);
+    return out2;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = v;
+  return out;
+}
+async function handleApprovalEvents(rawBody, headers, secret, opts) {
+  const raw = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+  const sig = verifyAstraSyncWebhook(raw, toHeaderRecord(headers), secret, {
+    ...opts.toleranceSeconds !== void 0 && { toleranceSeconds: opts.toleranceSeconds },
+    ...opts.nowMs !== void 0 && { nowMs: opts.nowMs }
+  });
+  if (!sig.ok) return { status: 401, body: { ok: false, error: sig.reason } };
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return { status: 400, body: { ok: false, error: "invalid_json" } };
+  }
+  if (!event || typeof event.eventId !== "string" || typeof event.type !== "string") {
+    return { status: 400, body: { ok: false, error: "invalid_event" } };
+  }
+  if (!TYPES.has(event.type)) {
+    opts.onEvent?.(event, "ignored");
+    return { status: 200, body: { ok: true, eventId: event.eventId, outcome: "ignored" } };
+  }
+  const seen = opts.seen ?? defaultSeen;
+  const has = typeof seen === "function" ? seen : (id) => seen.has(id);
+  try {
+    if (await has(event.eventId)) {
+      opts.onEvent?.(event, "duplicate");
+      return { status: 200, body: { ok: true, eventId: event.eventId, outcome: "duplicate" } };
+    }
+    const candidates = event.protocol ? opts.kits.filter((k) => k.protocol === event.protocol) : opts.kits;
+    let last = "not_found";
+    let terminal = true;
+    for (const kit of candidates) {
+      const r = await kit.applyApprovalEvent(event);
+      last = r.outcome;
+      terminal = r.terminal;
+      if (r.outcome !== "not_found") break;
+    }
+    opts.onEvent?.(event, last);
+    if (!terminal) {
+      return { status: 503, body: { ok: false, eventId: event.eventId, outcome: last } };
+    }
+    if (typeof seen !== "function") await seen.add(event.eventId);
+    return { status: 200, body: { ok: true, eventId: event.eventId, outcome: last } };
+  } catch (err) {
+    return {
+      status: 503,
+      body: {
+        ok: false,
+        eventId: event.eventId,
+        error: err instanceof Error ? err.message : "transient_error"
+      }
+    };
+  }
+}
+
 // src/adapters/kit-express.ts
 var bytes = (b) => b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
 function rawBodyOf(req) {
@@ -51,11 +194,46 @@ function rawBodyOf(req) {
   }
   return void 0;
 }
+var first = (v) => (Array.isArray(v) ? v[0] : v)?.split(",")[0]?.trim() || void 0;
+function originOf(req, publicOrigin) {
+  if (publicOrigin) return publicOrigin.replace(/\/+$/, "");
+  const trustProxy = Boolean(req.app?.get("trust proxy"));
+  const host = trustProxy && first(req.headers["x-forwarded-host"]) || req.get?.("host") || req.headers.host || "localhost";
+  const proto = trustProxy && first(req.headers["x-forwarded-proto"]) || req.protocol || "http";
+  return `${proto}://${host}`;
+}
+var isKit = (k) => typeof k.applyApprovalEvent === "function" && (k.protocol === "ucp" || k.protocol === "acp");
+async function writeEvents(req, res, secret, kits, seen) {
+  const raw = rawBodyOf(req);
+  const text = raw === void 0 ? "" : typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+  const out = secret ? await handleApprovalEvents(text, req.headers, secret, { kits, ...seen && { seen } }) : { status: 500, body: { ok: false, error: "webhook_secret_not_configured" } };
+  res.status(out.status);
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(out.body));
+}
+function approvalEventsHandler(options) {
+  return async (req, res, next) => {
+    try {
+      await writeEvents(req, res, options.secret, options.kits, options.seen);
+    } catch (err) {
+      next(err);
+    }
+  };
+}
 function expressHandler(kit, options = {}) {
   return async (req, res, next) => {
     try {
-      const host = req.get?.("host") ?? req.headers.host ?? "localhost";
-      const url = `${req.protocol ?? "http"}://${host}${req.originalUrl ?? req.url}`;
+      if (options.approvalEventsPath && req.method === "POST") {
+        const p = options.approvalEventsPath.replace(/\/+$/, "");
+        const full = (req.originalUrl ?? req.url).split("?")[0].replace(/\/+$/, "");
+        const local = req.url.split("?")[0].replace(/\/+$/, "");
+        if (full === p || local === p) {
+          const kits = options.approvalEventKits ?? (isKit(kit) ? [kit] : []);
+          await writeEvents(req, res, options.webhookSecret, kits, options.seenEvents);
+          return;
+        }
+      }
+      const url = `${originOf(req, kit.publicOrigin)}${req.originalUrl ?? req.url}`;
       const headers = new Headers();
       for (const [k, v] of Object.entries(req.headers)) {
         if (v === void 0) continue;
@@ -83,6 +261,7 @@ function expressHandler(kit, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  approvalEventsHandler,
   expressHandler
 });
 //# sourceMappingURL=kit-express.js.map