@operato/ops-contract 0.9.12 → 0.9.14

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './wms-profile.ts';
 export * from './yms-profile.ts';
 export * from './canonical-record.ts';
 export * from './webhook.ts';
+export * from './webhook-secret.ts';
 export * from './oee.ts';
 export * from './rated-usage.ts';
 export * from './yield.ts';

package/dist/index.js

@@ -40,6 +40,8 @@ export * from "./yms-profile.js";
 export * from "./canonical-record.js";
 /* `webhook-signature.ts` 는 여기 없다 — `node:crypto` 를 쓰므로 `@operato/ops-contract/webhook` 으로만 나간다. */
 export * from "./webhook.js";
+/* 비밀값 **이름** 규약 — 값을 읽지 않으므로 여기서 나간다(§`webhook-secret`). */
+export * from "./webhook-secret.js";
 export * from "./oee.js";
 export * from "./rated-usage.js";
 export * from "./yield.js";

package/dist/webhook-secret.d.ts

@@ -0,0 +1,138 @@
+/**
+ * ① 이름 규약 — **두 벌로 나눈다.**
+ *
+ * 서명값은 대칭키다. 검증할 수 있는 쪽은 서명도 만들 수 있으므로, 한 벌로 두면 우리 사실을 검증하는
+ * 상대가 그 키로 우리에게 지시를 위조해 넣는다.
+ *
+ * ```
+ * 나가는 쪽이 새면   남의 시스템에 거짓 사실이 앉는다
+ * 들어오는 쪽이 새면 남이 우리 공장에 지시를 꽂고, 사람이 그것으로 물건을 만든다
+ * ```
+ *
+ * 뒤엣것이 더 무겁다. 무게가 다르면 키도 달라야 한다.
+ *
+ * `OUTBOX`/`INTAKE` 가 아니라 `SIGNING`/`VERIFY` 인 이유: 앞엣것은 **우리 구조**의 이름이고 구조는
+ * 바뀐다. 서명하나 검증하나는 그 키가 무엇에 쓰이는지라 모듈이 바뀌어도 안 바뀐다.
+ *
+ * `MES_` 가 아닌 이유: 이 계약은 한 제품의 것이 아니다(§`WEBHOOK_HEADER` 와 같은 판단).
+ */
+export declare const WEBHOOK_SECRET_BASE: {
+    /** 우리가 서명할 때 — 나가는 쪽. */
+    readonly signing: "WEBHOOK_SIGNING_SECRET";
+    /** 우리가 검증할 때 — 들어오는 쪽. */
+    readonly verify: "WEBHOOK_VERIFY_SECRET";
+};
+export type WebhookSecretPurpose = keyof typeof WEBHOOK_SECRET_BASE;
+/**
+ * ② 파생 규칙이 성립하려면 이름이 이 모양이어야 한다 — 소문자·숫자, 이음은 하이픈 하나.
+ *
+ * ── 왜 부호화하지 않고 입력을 좁혔나 ───────────────────────────────────────
+ * 환경 변수 이름에는 `[A-Za-z0-9_]` 만 쓸 수 있다. 그래서 도메인 이름을 그 집합으로 접어야 하는데,
+ * 접으면 **두 이름이 한 이름으로 눌린다** — plant 의 규칙이 `a-b` 와 `a_b` 를 둘 다 `A_B` 로 만들고
+ * 있었고, 눌리면 한 도메인이 다른 도메인의 키로 열린다. 그 파일은 그 사실을 주석으로 알고 있었다.
+ *
+ * 부호화(`_2D` 같은 것)로 풀 수도 있지만, 이 이름은 **사람이 비밀 관리 도구에 손으로 넣는 값**이다.
+ * `MIRATEK_2DGUNSAN` 을 읽고 쓰게 하면 그 자리에서 다른 실수가 난다.
+ *
+ * 그래서 접는 것을 없애는 대신 **접을 필요가 없는 입력만 받는다.** 밑줄이 없는 이름에서
+ * `-` → `_` 는 되돌릴 수 있고, 눌리지 않는다. 하이픈이 연달아 오지 못하게 한 것은 구분자
+ * `__` 가 그 자리에서만 나오게 하려는 것이다.
+ *
+ * 이 모양이 아닌 이름은 **거절한다.** 접어서 통과시키면 그 순간부터 눌림이 조용히 산다.
+ */
+export declare const WEBHOOK_SECRET_NAME_SHAPE: RegExp;
+/** 그 조각이 파생에 쓸 수 있는 모양인가. */
+export declare function isWebhookSecretSegment(segment: string): boolean;
+/**
+ * ② 파생 — `(base, domain, peer?)` → 환경 변수 이름.
+ *
+ * ```
+ * ('WEBHOOK_VERIFY_SECRET', 'miratek-gunsan', 'twin-a')  →  WEBHOOK_VERIFY_SECRET__MIRATEK_GUNSAN__TWIN_A
+ * ('WEBHOOK_SIGNING_SECRET', 'miratek-gunsan')           →  WEBHOOK_SIGNING_SECRET__MIRATEK_GUNSAN
+ * ```
+ *
+ * **되돌릴 수 있다.** 조각에 밑줄이 없으니 `__` 는 구분자에서만 나오고, `_` 는 하이픈에서만 나온다.
+ * 그래서 두 쌍이 한 이름으로 눌릴 수 없다.
+ *
+ * 모양이 아닌 조각은 던진다 — 접어 통과시키면 눌림이 생기고, 눌림은 **한 공장이 다른 공장의 키로
+ * 열리는** 것이다. 이름을 정하는 자리에서 걸리는 것이 낫다.
+ */
+export declare function webhookSecretEnvName(base: string, domain: string, peer?: string): string;
+/** 이 후보가 무엇까지 고정하나 — 사다리의 칸을 이 값으로 판단한다. */
+export type WebhookSecretPin = 'peer' | 'domain' | 'installation';
+export interface WebhookSecretCandidate {
+    /** 찾아볼 환경 변수 이름. */
+    name: string;
+    /** 이 이름이 무엇까지 고정하나. */
+    pins: WebhookSecretPin;
+    /** 배포된 설치본을 안 깨뜨리려고 남긴 칸인가 — 열리면 알려야 한다. */
+    compatibility: boolean;
+}
+export interface WebhookSecretLookup {
+    purpose: WebhookSecretPurpose;
+    /** 우리 테넌트의 subdomain. */
+    domain: string;
+    /** 상대의 이름 — **우리 이름이 아니다.** */
+    peer: string;
+    /**
+     * 옛 이름들 — 이 설치본이 예전에 쓰던 변수. 배포된 것을 안 깨뜨리려고 받는다.
+     *
+     * 옛 이름을 끊으면 그 이름으로만 돌아가는 설치본의 사실이 그 순간 멈춘다. 그래서 지우지 않고
+     * 받되, 열리면 부르는 쪽이 한 번 알린다 — 조용히 되면 아무도 새 이름으로 옮기지 않는다.
+     */
+    legacyBases?: readonly string[];
+    /**
+     * **검증 쪽에서 넓은 칸까지 내려가는 것을 허락한다.** 기본은 거짓이고, 그것이 ③ 규칙이다.
+     *
+     * 이 인자를 참으로 주려면 부르는 쪽이 **그 도메인에 상대가 하나뿐임을 확인**해야 한다. 둘이면
+     * 둘이 같은 키로 풀리고, 그 순간 주소가 「이 사실이 누구 것인가」를 정하는데 아무도 그것을
+     * 검사하지 않는다 — 상대 A 가 제대로 서명한 봉투를 상대 B 의 주소에 앉힐 수 있다
+     * (§`webhook-signature` 의 불변식: 주소는 키가 이미 고정한 것만 정할 수 있다).
+     *
+     * 그리고 그 상태는 **두 번째 상대가 붙는 날 아무 경고 없이 끝난다.** 이름을 명시적으로 주게 한
+     * 이유가 그것이다 — 코드에서 찾을 수 있어야 한다.
+     */
+    allowSinglePeerFallback?: boolean;
+}
+/**
+ * ③ 사다리 — 찾아볼 이름을 순서대로.
+ *
+ * ```
+ * 서명(나가는 쪽)   상대별 → 도메인별 → 옛 이름           우리가 상대를 알고 보낸다
+ * 검증(들어오는 쪽)  상대별 하나                            넓은 칸으로 내려가지 않는다
+ * ```
+ *
+ * **나누는 선은 「고정 범위가 넓어지는가」다.** 같은 것을 고정한 채 이름만 옛것인 칸은 내려가도
+ * 되고, 고정 범위가 넓어지는 칸은 안 된다. 검증 쪽에서 넓어지면 아무 상대나 통과한다.
+ *
+ * 검증 쪽이 못 찾으면 ④ 로 간다 — 거절한다. 「안 붙었다」와 「붙었는데 아무 키나 통한다」는 다른
+ * 상태이고, 뒤엣것은 사람이 볼 수 없다.
+ */
+export declare function webhookSecretCandidates(lookup: WebhookSecretLookup): WebhookSecretCandidate[];
+/**
+ * ④ 없을 때 — **거절한다. 그리고 응답에 변수 이름을 넣지 않는다.**
+ *
+ * 거절 사유는 이미 있다(`WebhookSignatureFailure` 의 `'no-secret'`). 그 사유는 응답에 나가도 된다 —
+ * 보내는 쪽이 무엇을 고쳐야 하는지 알아야 한다.
+ *
+ * **변수 이름은 나가면 안 된다.** 자격을 못 낸 요청에 「이 이름의 변수를 채우면 열린다」고 답하는
+ * 것이고, 그 이름이 키 선택 방식과 **어떤 상대가 등록되어 있는지**를 함께 말한다.
+ *
+ * 그래서 이 문장은 **로그용**이다. 운영하는 사람은 프로세스 로그를 보고, 요청을 보낸 쪽은 못 본다.
+ */
+export declare function webhookSecretMissingNote(candidates: readonly WebhookSecretCandidate[]): string;
+/**
+ * 사다리를 실제로 걸어 값을 찾는다 — 환경을 **인자로 받는다.**
+ *
+ * `process.env` 를 여기서 읽지 않는 이유는 머리말과 같다. 그리고 시험이 값을 손에 들고 걸을 수 있다.
+ *
+ * 돌려주는 것에 **어느 칸에서 열렸는지**가 있다. `compatibility` 가 참인 칸에서 열렸으면 부르는 쪽이
+ * 한 번 알린다 — 조용히 되면 아무도 새 이름으로 옮기지 않는다.
+ */
+export declare function webhookSecretFrom(env: Record<string, string | undefined>, lookup: WebhookSecretLookup): {
+    secret: string;
+    opened: WebhookSecretCandidate;
+} | {
+    secret: undefined;
+    tried: WebhookSecretCandidate[];
+};

package/dist/webhook-secret.js

@@ -0,0 +1,154 @@
+/*
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 어느 키가 어느 문을 여는가 — **이름 규약 · 파생 · 사다리 · 없을 때.**
+ *
+ * ── 왜 계약에 있나 (2026-09-08) ────────────────────────────────────────────
+ * 이 넷을 `operato-plant` 안에서 정하고 있었다(`server/service/domain-secret.ts`). 앱이 정하면
+ * `operato-wms` 가 붙는 날 그쪽이 또 적고, 셋이 **서로 다른 사다리**를 갖는다. 그러면 「이 설치본은
+ * 어느 키까지 내려가나」에 답할 자리가 없다.
+ *
+ * 그리고 이 넷은 서명과 검증이 **한 글자까지 같아야** 성립한다 — 서명 입력이 그런 것과 같은
+ * 이유로(§`webhook-signature`) 만드는 규칙과 찾는 규칙이 한 파일에 있어야 한다.
+ *
+ * ── 값은 여기 없다 ────────────────────────────────────────────────────────
+ * 이 파일은 **이름만** 만든다. `process.env` 를 읽지 않는다 — 그래야 규칙을 값 없이 시험할 수 있고,
+ * 이 패키지를 쓰는 브라우저 번들이 `node:process` 를 묶으려 하지 않는다. 읽는 것은 부르는 쪽이다.
+ *
+ * 비밀값은 표에 두지 않는다(§`WebhookDestination.params` 도 같은 규율). 데이터베이스·백업·화면
+ * 기록에 남고 한 번 새면 되돌릴 수 없다. **값은 환경에 있고, 어느 상대 것인지는 이름이 말한다.**
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * ① 이름 규약 — **두 벌로 나눈다.**
+ *
+ * 서명값은 대칭키다. 검증할 수 있는 쪽은 서명도 만들 수 있으므로, 한 벌로 두면 우리 사실을 검증하는
+ * 상대가 그 키로 우리에게 지시를 위조해 넣는다.
+ *
+ * ```
+ * 나가는 쪽이 새면   남의 시스템에 거짓 사실이 앉는다
+ * 들어오는 쪽이 새면 남이 우리 공장에 지시를 꽂고, 사람이 그것으로 물건을 만든다
+ * ```
+ *
+ * 뒤엣것이 더 무겁다. 무게가 다르면 키도 달라야 한다.
+ *
+ * `OUTBOX`/`INTAKE` 가 아니라 `SIGNING`/`VERIFY` 인 이유: 앞엣것은 **우리 구조**의 이름이고 구조는
+ * 바뀐다. 서명하나 검증하나는 그 키가 무엇에 쓰이는지라 모듈이 바뀌어도 안 바뀐다.
+ *
+ * `MES_` 가 아닌 이유: 이 계약은 한 제품의 것이 아니다(§`WEBHOOK_HEADER` 와 같은 판단).
+ */
+export const WEBHOOK_SECRET_BASE = {
+    /** 우리가 서명할 때 — 나가는 쪽. */
+    signing: 'WEBHOOK_SIGNING_SECRET',
+    /** 우리가 검증할 때 — 들어오는 쪽. */
+    verify: 'WEBHOOK_VERIFY_SECRET'
+};
+/**
+ * ② 파생 규칙이 성립하려면 이름이 이 모양이어야 한다 — 소문자·숫자, 이음은 하이픈 하나.
+ *
+ * ── 왜 부호화하지 않고 입력을 좁혔나 ───────────────────────────────────────
+ * 환경 변수 이름에는 `[A-Za-z0-9_]` 만 쓸 수 있다. 그래서 도메인 이름을 그 집합으로 접어야 하는데,
+ * 접으면 **두 이름이 한 이름으로 눌린다** — plant 의 규칙이 `a-b` 와 `a_b` 를 둘 다 `A_B` 로 만들고
+ * 있었고, 눌리면 한 도메인이 다른 도메인의 키로 열린다. 그 파일은 그 사실을 주석으로 알고 있었다.
+ *
+ * 부호화(`_2D` 같은 것)로 풀 수도 있지만, 이 이름은 **사람이 비밀 관리 도구에 손으로 넣는 값**이다.
+ * `MIRATEK_2DGUNSAN` 을 읽고 쓰게 하면 그 자리에서 다른 실수가 난다.
+ *
+ * 그래서 접는 것을 없애는 대신 **접을 필요가 없는 입력만 받는다.** 밑줄이 없는 이름에서
+ * `-` → `_` 는 되돌릴 수 있고, 눌리지 않는다. 하이픈이 연달아 오지 못하게 한 것은 구분자
+ * `__` 가 그 자리에서만 나오게 하려는 것이다.
+ *
+ * 이 모양이 아닌 이름은 **거절한다.** 접어서 통과시키면 그 순간부터 눌림이 조용히 산다.
+ */
+export const WEBHOOK_SECRET_NAME_SHAPE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** 그 조각이 파생에 쓸 수 있는 모양인가. */
+export function isWebhookSecretSegment(segment) {
+    return WEBHOOK_SECRET_NAME_SHAPE.test(segment);
+}
+/**
+ * ② 파생 — `(base, domain, peer?)` → 환경 변수 이름.
+ *
+ * ```
+ * ('WEBHOOK_VERIFY_SECRET', 'miratek-gunsan', 'twin-a')  →  WEBHOOK_VERIFY_SECRET__MIRATEK_GUNSAN__TWIN_A
+ * ('WEBHOOK_SIGNING_SECRET', 'miratek-gunsan')           →  WEBHOOK_SIGNING_SECRET__MIRATEK_GUNSAN
+ * ```
+ *
+ * **되돌릴 수 있다.** 조각에 밑줄이 없으니 `__` 는 구분자에서만 나오고, `_` 는 하이픈에서만 나온다.
+ * 그래서 두 쌍이 한 이름으로 눌릴 수 없다.
+ *
+ * 모양이 아닌 조각은 던진다 — 접어 통과시키면 눌림이 생기고, 눌림은 **한 공장이 다른 공장의 키로
+ * 열리는** 것이다. 이름을 정하는 자리에서 걸리는 것이 낫다.
+ */
+export function webhookSecretEnvName(base, domain, peer) {
+    const segments = peer === undefined ? [domain] : [domain, peer];
+    for (const segment of segments) {
+        if (!isWebhookSecretSegment(segment)) {
+            throw new Error(`webhookSecretEnvName: "${segment}" 는 비밀값 이름에 쓸 수 없다 — ` +
+                '소문자·숫자와 이음 하이픈만 쓴다(예: miratek-gunsan). ' +
+                '밑줄이나 대문자가 섞이면 두 이름이 한 환경 변수로 눌리고, 한 쪽이 다른 쪽의 키로 열린다.');
+        }
+    }
+    return [base, ...segments.map(s => s.toUpperCase().replace(/-/g, '_'))].join('__');
+}
+/**
+ * ③ 사다리 — 찾아볼 이름을 순서대로.
+ *
+ * ```
+ * 서명(나가는 쪽)   상대별 → 도메인별 → 옛 이름           우리가 상대를 알고 보낸다
+ * 검증(들어오는 쪽)  상대별 하나                            넓은 칸으로 내려가지 않는다
+ * ```
+ *
+ * **나누는 선은 「고정 범위가 넓어지는가」다.** 같은 것을 고정한 채 이름만 옛것인 칸은 내려가도
+ * 되고, 고정 범위가 넓어지는 칸은 안 된다. 검증 쪽에서 넓어지면 아무 상대나 통과한다.
+ *
+ * 검증 쪽이 못 찾으면 ④ 로 간다 — 거절한다. 「안 붙었다」와 「붙었는데 아무 키나 통한다」는 다른
+ * 상태이고, 뒤엣것은 사람이 볼 수 없다.
+ */
+export function webhookSecretCandidates(lookup) {
+    const { purpose, domain, peer, legacyBases = [], allowSinglePeerFallback = false } = lookup;
+    const base = WEBHOOK_SECRET_BASE[purpose];
+    const out = [
+        { name: webhookSecretEnvName(base, domain, peer), pins: 'peer', compatibility: false }
+    ];
+    /* 검증은 여기서 멈춘다 — 확인한 사람이 명시적으로 열지 않는 한. */
+    if (purpose === 'verify' && !allowSinglePeerFallback)
+        return out;
+    out.push({ name: webhookSecretEnvName(base, domain), pins: 'domain', compatibility: purpose === 'verify' });
+    for (const legacy of legacyBases) {
+        out.push({ name: webhookSecretEnvName(legacy, domain), pins: 'domain', compatibility: true });
+        out.push({ name: legacy, pins: 'installation', compatibility: true });
+    }
+    return out;
+}
+/**
+ * ④ 없을 때 — **거절한다. 그리고 응답에 변수 이름을 넣지 않는다.**
+ *
+ * 거절 사유는 이미 있다(`WebhookSignatureFailure` 의 `'no-secret'`). 그 사유는 응답에 나가도 된다 —
+ * 보내는 쪽이 무엇을 고쳐야 하는지 알아야 한다.
+ *
+ * **변수 이름은 나가면 안 된다.** 자격을 못 낸 요청에 「이 이름의 변수를 채우면 열린다」고 답하는
+ * 것이고, 그 이름이 키 선택 방식과 **어떤 상대가 등록되어 있는지**를 함께 말한다.
+ *
+ * 그래서 이 문장은 **로그용**이다. 운영하는 사람은 프로세스 로그를 보고, 요청을 보낸 쪽은 못 본다.
+ */
+export function webhookSecretMissingNote(candidates) {
+    const names = candidates.map(c => c.name).join(' · ');
+    return (`비밀값이 없어 거절했다 — 찾아본 이름: ${names}. ` +
+        '이 문장은 로그에만 남긴다(응답에 변수 이름을 넣으면 자격 없는 요청에 키 선택 방식과 등록된 상대를 알려 준다).');
+}
+/**
+ * 사다리를 실제로 걸어 값을 찾는다 — 환경을 **인자로 받는다.**
+ *
+ * `process.env` 를 여기서 읽지 않는 이유는 머리말과 같다. 그리고 시험이 값을 손에 들고 걸을 수 있다.
+ *
+ * 돌려주는 것에 **어느 칸에서 열렸는지**가 있다. `compatibility` 가 참인 칸에서 열렸으면 부르는 쪽이
+ * 한 번 알린다 — 조용히 되면 아무도 새 이름으로 옮기지 않는다.
+ */
+export function webhookSecretFrom(env, lookup) {
+    const candidates = webhookSecretCandidates(lookup);
+    for (const candidate of candidates) {
+        const value = env[candidate.name]?.trim();
+        if (value)
+            return { secret: value, opened: candidate };
+    }
+    return { secret: undefined, tried: candidates };
+}

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

@@ -72,6 +72,8 @@ __export(index_exports, {
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE: () => VOCABULARY_TYPE,
+  WEBHOOK_SECRET_BASE: () => WEBHOOK_SECRET_BASE,
+  WEBHOOK_SECRET_NAME_SHAPE: () => WEBHOOK_SECRET_NAME_SHAPE,
   WEBHOOK_STATUS: () => WEBHOOK_STATUS,
   WEBHOOK_TOO_MANY: () => WEBHOOK_TOO_MANY,
   WMS_LOCATION_TYPES: () => WMS_LOCATION_TYPES,
@@ -157,6 +159,7 @@ __export(index_exports, {
   isPlannedStopStatus: () => isPlannedStopStatus,
   isResourceKind: () => isResourceKind,
   isTransformationRecord: () => isTransformationRecord,
+  isWebhookSecretSegment: () => isWebhookSecretSegment,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
   judgeAgainstSpec: () => judgeAgainstSpec,
@@ -219,6 +222,10 @@ __export(index_exports, {
   validateEpcisEvent: () => validateEpcisEvent,
   validatePerformance: () => validatePerformance,
   validateScenario: () => validateScenario,
+  webhookSecretCandidates: () => webhookSecretCandidates,
+  webhookSecretEnvName: () => webhookSecretEnvName,
+  webhookSecretFrom: () => webhookSecretFrom,
+  webhookSecretMissingNote: () => webhookSecretMissingNote,
   webhookSenderAction: () => webhookSenderAction,
   weekdayAt: () => weekdayAt,
   workingHoursBetween: () => workingHoursBetween,
@@ -4053,6 +4060,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 +4077,7 @@ function webhookSenderAction(status) {
     case WEBHOOK_STATUS.unsupported:
       return "stop";
     default:
-      return status >= 500 ? "retry" : "stop";
+      return "retry";
   }
 }
 var WEBHOOK_TOO_MANY = 429;
@@ -4086,6 +4102,55 @@ function checkSequenceRun(lastSeq, seqs) {
   return { accepted, lastSeq: cursor };
 }
 
+// src/webhook-secret.ts
+var WEBHOOK_SECRET_BASE = {
+  /** 우리가 서명할 때 — 나가는 쪽. */
+  signing: "WEBHOOK_SIGNING_SECRET",
+  /** 우리가 검증할 때 — 들어오는 쪽. */
+  verify: "WEBHOOK_VERIFY_SECRET"
+};
+var WEBHOOK_SECRET_NAME_SHAPE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function isWebhookSecretSegment(segment) {
+  return WEBHOOK_SECRET_NAME_SHAPE.test(segment);
+}
+function webhookSecretEnvName(base, domain, peer) {
+  const segments = peer === void 0 ? [domain] : [domain, peer];
+  for (const segment of segments) {
+    if (!isWebhookSecretSegment(segment)) {
+      throw new Error(
+        `webhookSecretEnvName: "${segment}" \uB294 \uBE44\uBC00\uAC12 \uC774\uB984\uC5D0 \uC4F8 \uC218 \uC5C6\uB2E4 \u2014 \uC18C\uBB38\uC790\xB7\uC22B\uC790\uC640 \uC774\uC74C \uD558\uC774\uD508\uB9CC \uC4F4\uB2E4(\uC608: miratek-gunsan). \uBC11\uC904\uC774\uB098 \uB300\uBB38\uC790\uAC00 \uC11E\uC774\uBA74 \uB450 \uC774\uB984\uC774 \uD55C \uD658\uACBD \uBCC0\uC218\uB85C \uB20C\uB9AC\uACE0, \uD55C \uCABD\uC774 \uB2E4\uB978 \uCABD\uC758 \uD0A4\uB85C \uC5F4\uB9B0\uB2E4.`
+      );
+    }
+  }
+  return [base, ...segments.map((s) => s.toUpperCase().replace(/-/g, "_"))].join("__");
+}
+function webhookSecretCandidates(lookup) {
+  const { purpose, domain, peer, legacyBases = [], allowSinglePeerFallback = false } = lookup;
+  const base = WEBHOOK_SECRET_BASE[purpose];
+  const out = [
+    { name: webhookSecretEnvName(base, domain, peer), pins: "peer", compatibility: false }
+  ];
+  if (purpose === "verify" && !allowSinglePeerFallback) return out;
+  out.push({ name: webhookSecretEnvName(base, domain), pins: "domain", compatibility: purpose === "verify" });
+  for (const legacy of legacyBases) {
+    out.push({ name: webhookSecretEnvName(legacy, domain), pins: "domain", compatibility: true });
+    out.push({ name: legacy, pins: "installation", compatibility: true });
+  }
+  return out;
+}
+function webhookSecretMissingNote(candidates) {
+  const names = candidates.map((c) => c.name).join(" \xB7 ");
+  return `\uBE44\uBC00\uAC12\uC774 \uC5C6\uC5B4 \uAC70\uC808\uD588\uB2E4 \u2014 \uCC3E\uC544\uBCF8 \uC774\uB984: ${names}. \uC774 \uBB38\uC7A5\uC740 \uB85C\uADF8\uC5D0\uB9CC \uB0A8\uAE34\uB2E4(\uC751\uB2F5\uC5D0 \uBCC0\uC218 \uC774\uB984\uC744 \uB123\uC73C\uBA74 \uC790\uACA9 \uC5C6\uB294 \uC694\uCCAD\uC5D0 \uD0A4 \uC120\uD0DD \uBC29\uC2DD\uACFC \uB4F1\uB85D\uB41C \uC0C1\uB300\uB97C \uC54C\uB824 \uC900\uB2E4).`;
+}
+function webhookSecretFrom(env, lookup) {
+  const candidates = webhookSecretCandidates(lookup);
+  for (const candidate of candidates) {
+    const value = env[candidate.name]?.trim();
+    if (value) return { secret: value, opened: candidate };
+  }
+  return { secret: void 0, tried: candidates };
+}
+
 // src/oee.ts
 function computeOee(c, nowMs) {
   const missing = [];
@@ -4443,6 +4508,8 @@ function commandSpecGaps(specs, command) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_SECRET_BASE,
+  WEBHOOK_SECRET_NAME_SHAPE,
   WEBHOOK_STATUS,
   WEBHOOK_TOO_MANY,
   WMS_LOCATION_TYPES,
@@ -4528,6 +4595,7 @@ function commandSpecGaps(specs, command) {
   isPlannedStopStatus,
   isResourceKind,
   isTransformationRecord,
+  isWebhookSecretSegment,
   isoDurationHours,
   itemKeyOf,
   judgeAgainstSpec,
@@ -4590,6 +4658,10 @@ function commandSpecGaps(specs, command) {
   validateEpcisEvent,
   validatePerformance,
   validateScenario,
+  webhookSecretCandidates,
+  webhookSecretEnvName,
+  webhookSecretFrom,
+  webhookSecretMissingNote,
   webhookSenderAction,
   weekdayAt,
   workingHoursBetween,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "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",