@operato/ops-contract 0.9.12 → 0.9.13

package/dist/webhook-signature.js

@@ -44,6 +44,43 @@ export const WEBHOOK_TOLERANCE_MS = 5 * 60_000;
 export function webhookSigningInput(timestamp, body) {
     return `${timestamp}.${body}`;
 }
+/*
+ * ═══════════════════════════════════════════════════════════════════════════
+ * What the signature does **not** cover — and the one rule that follows.
+ *
+ * ── The scope, stated plainly (2026-09-08) ─────────────────────────────────
+ * The signed string is `timestamp.body`. The **request path is not signed**, and neither is
+ * any header other than the timestamp. `x-ops-source` says who is sending, and it is signed
+ * by nothing at all — which is why it is declared for logging and never for identity.
+ *
+ * ── Why a peer segment in the path is still safe ──────────────────────────
+ * The receiving side has to know which key to verify with, and the sender's identity is the
+ * thing it needs in order to choose. Putting that in the path is sound, but not because the
+ * signature protects the path — it does not. It is sound because **the path only selects the
+ * key, and the key is what proves the identity.** A request signed with peer A's key, moved
+ * onto peer B's path, fails: it is verified against B's key and does not match.
+ *
+ * That distinction matters. "The signature covers the route" would license signing nothing
+ * and trusting the URL, and this scheme does not support that.
+ *
+ * ── The rule ──────────────────────────────────────────────────────────────
+ * **The path may only decide what the key already pins.**
+ *
+ * A per-peer path is meaningful exactly as long as two peers cannot resolve to the same
+ * verifying key. The moment they share one — most easily through a compatibility fallback
+ * that lands both on a domain-wide or installation-wide value — the path is deciding
+ * something the key does not, and peer A can place a validly signed request on peer B's
+ * path. Nothing rejects it, and the receiving side records it as B's.
+ *
+ * So a fallback ladder for continuity is fine on the rungs that keep the same pin (an older
+ * name for the same domain's key), and not fine on the rung that widens it (two peers of one
+ * domain sharing a value) — unless that domain has exactly one peer, which is a state that
+ * ends without warning the day a second one is added.
+ *
+ * The same rule is why the receiving tenant is not taken from the path alone: the key has to
+ * pin the tenant too, or a valid envelope can be redirected into another factory's journal.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
 /** 서명을 만든다 — hex. */
 export function signWebhook(secret, timestamp, body) {
     return createHmac('sha256', secret).update(webhookSigningInput(timestamp, body)).digest('hex');

package/dist/webhook.d.ts

@@ -45,8 +45,29 @@ export type WebhookSenderAction = 'accepted' | 'partial' | 'resend-from' | 'wait
  * 응답 코드 → 보내는 쪽의 행동. **모르는 코드도 답을 낸다.**
  *
  * 표에 없는 코드가 오는 일이 있다(프록시의 502, 게이트웨이의 504). 그때 「모른다」로 두면 보내는 쪽이
- * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다. 5xx 는 받는 쪽 사정이므로 다시 보내고, 나머지는
- * 보낸 것이 잘못이므로 멈춘다.
+ * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다.
+ *
+ * ── 모르는 코드는 `retry` 다 (2026-09-08 실측으로 바꿨다) ────────────────────
+ * 이 함수는 `status >= 500 ? 'retry' : 'stop'` 이었다. 「4xx 는 보낸 것이 잘못이다」는 읽기였는데,
+ * **모르는 4xx 에는 그 읽기가 성립하지 않는다.**
+ *
+ * 실측: 트윈이 재기동하는 짧은 사이에 405 가 나갔고, 405 는 이 표에 없어서 `stop` 이 되었다.
+ * 보내는 쪽은 719 건을 `FAILED` 로 옮기고 다시 보내지 않았다. **문이 아직 안 붙은 상태였고 봉투는
+ * 멀쩡했다** — 몇 초 뒤에 보냈으면 다 들어갔다.
+ *
+ * 판단의 근거는 어느 쪽이 더 그럴듯하냐가 아니라 **틀렸을 때의 값**이다.
+ *
+ * ```
+ * 잘못 retry 했다   재시도 예산을 쓴다. 예산이 끝나면 FAILED 로 서고 사람이 본다
+ * 잘못 stop 했다    사실이 흐름에서 빠진다. 되보내는 문이 없으면 영구 손실
+ * ```
+ *
+ * 모르는 4xx 중 여럿이 실제로 잠깐이다 — 408(타임아웃) · 425(너무 이름) · 405(문이 아직 없음).
+ * 그리고 `429` 를 이 표 밖에 따로 든 것이 같은 부류였다: 표에 없는데 `stop` 이면 안 되는 코드였고,
+ * 그래서 계약이 예외로 들었다. 하나씩 표에 더하는 것보다 **기본값을 안전한 쪽으로 두는 것**이 맞다.
+ *
+ * 멈추는 것은 표에 적힌 넷뿐이다(400·401·404·501). 그 넷은 「봉투가 틀렸다」·「자격이 틀렸다」·
+ * 「대상이 없다」·「그 커넥터가 밀어 받기를 모른다」이고, 다시 보내도 같다는 것이 **선언된 사실**이다.
  */
 export declare function webhookSenderAction(status: number): WebhookSenderAction;
 /** 429 를 함께 쓰는 곳이 있다 — 받는 쪽이 따라가지 못한다는 뜻이고, 행동은 503 과 같다. */

package/dist/webhook.js

@@ -49,8 +49,29 @@ export const WEBHOOK_STATUS = {
  * 응답 코드 → 보내는 쪽의 행동. **모르는 코드도 답을 낸다.**
  *
  * 표에 없는 코드가 오는 일이 있다(프록시의 502, 게이트웨이의 504). 그때 「모른다」로 두면 보내는 쪽이
- * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다. 5xx 는 받는 쪽 사정이므로 다시 보내고, 나머지는
- * 보낸 것이 잘못이므로 멈춘다.
+ * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다.
+ *
+ * ── 모르는 코드는 `retry` 다 (2026-09-08 실측으로 바꿨다) ────────────────────
+ * 이 함수는 `status >= 500 ? 'retry' : 'stop'` 이었다. 「4xx 는 보낸 것이 잘못이다」는 읽기였는데,
+ * **모르는 4xx 에는 그 읽기가 성립하지 않는다.**
+ *
+ * 실측: 트윈이 재기동하는 짧은 사이에 405 가 나갔고, 405 는 이 표에 없어서 `stop` 이 되었다.
+ * 보내는 쪽은 719 건을 `FAILED` 로 옮기고 다시 보내지 않았다. **문이 아직 안 붙은 상태였고 봉투는
+ * 멀쩡했다** — 몇 초 뒤에 보냈으면 다 들어갔다.
+ *
+ * 판단의 근거는 어느 쪽이 더 그럴듯하냐가 아니라 **틀렸을 때의 값**이다.
+ *
+ * ```
+ * 잘못 retry 했다   재시도 예산을 쓴다. 예산이 끝나면 FAILED 로 서고 사람이 본다
+ * 잘못 stop 했다    사실이 흐름에서 빠진다. 되보내는 문이 없으면 영구 손실
+ * ```
+ *
+ * 모르는 4xx 중 여럿이 실제로 잠깐이다 — 408(타임아웃) · 425(너무 이름) · 405(문이 아직 없음).
+ * 그리고 `429` 를 이 표 밖에 따로 든 것이 같은 부류였다: 표에 없는데 `stop` 이면 안 되는 코드였고,
+ * 그래서 계약이 예외로 들었다. 하나씩 표에 더하는 것보다 **기본값을 안전한 쪽으로 두는 것**이 맞다.
+ *
+ * 멈추는 것은 표에 적힌 넷뿐이다(400·401·404·501). 그 넷은 「봉투가 틀렸다」·「자격이 틀렸다」·
+ * 「대상이 없다」·「그 커넥터가 밀어 받기를 모른다」이고, 다시 보내도 같다는 것이 **선언된 사실**이다.
  */
 export function webhookSenderAction(status) {
     switch (status) {
@@ -66,6 +87,15 @@ export function webhookSenderAction(status) {
             return 'partial';
         case WEBHOOK_STATUS.notLive:
             return 'wait';
+        /*
+         * 429 — 「따라오지 못한다」. 표 밖이지만 `wait` 이어야 한다.
+         *
+         * 기본값이 `retry` 가 된 뒤에도 이것은 따로 든다. 곧바로 다시 보내면 그 상태를 더 악화시키고,
+         * 받는 쪽이 준 `retryAfterMs` 를 무시하게 된다. 기본값 변경이 이 예외를 삼키는 것을 시험이
+         * 잡았다(§`sender-action-unknown-status.test.ts`).
+         */
+        case WEBHOOK_TOO_MANY:
+            return 'wait';
         case WEBHOOK_STATUS.failed:
             return 'retry';
         case WEBHOOK_STATUS.badPayload:
@@ -74,7 +104,12 @@ export function webhookSenderAction(status) {
         case WEBHOOK_STATUS.unsupported:
             return 'stop';
         default:
-            return status >= 500 ? 'retry' : 'stop';
+            /*
+             * 모르는 코드는 사실을 들고 있는다. 5xx 는 받는 쪽 사정이라 처음부터 그랬고, 모르는 4xx 도
+             * 같은 쪽으로 둔다 — 그것이 잠깐인 경우가 실제로 있고(§ 위 머리말), 틀렸을 때 잃는 것이
+             * 재시도 예산뿐이다.
+             */
+            return 'retry';
     }
 }
 /** 429 를 함께 쓰는 곳이 있다 — 받는 쪽이 따라가지 못한다는 뜻이고, 행동은 503 과 같다. */

package/dist-cjs/index.cjs

@@ -4053,6 +4053,15 @@ function webhookSenderAction(status) {
       return "partial";
     case WEBHOOK_STATUS.notLive:
       return "wait";
+    /*
+     * 429 — 「따라오지 못한다」. 표 밖이지만 `wait` 이어야 한다.
+     *
+     * 기본값이 `retry` 가 된 뒤에도 이것은 따로 든다. 곧바로 다시 보내면 그 상태를 더 악화시키고,
+     * 받는 쪽이 준 `retryAfterMs` 를 무시하게 된다. 기본값 변경이 이 예외를 삼키는 것을 시험이
+     * 잡았다(§`sender-action-unknown-status.test.ts`).
+     */
+    case WEBHOOK_TOO_MANY:
+      return "wait";
     case WEBHOOK_STATUS.failed:
       return "retry";
     case WEBHOOK_STATUS.badPayload:
@@ -4061,7 +4070,7 @@ function webhookSenderAction(status) {
     case WEBHOOK_STATUS.unsupported:
       return "stop";
     default:
-      return status >= 500 ? "retry" : "stop";
+      return "retry";
   }
 }
 var WEBHOOK_TOO_MANY = 429;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "description": "Operations domain contract — the standard vocabulary that producers and readers agree on (EPCIS 2.0/GS1, ISA-95, IEC 61850/ISO 50001). Types, guards, validation. No state, no engine.",
   "type": "module",
   "main": "./dist-cjs/index.cjs",