@operato/ops-contract 0.9.13 → 0.9.15

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-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,
@@ -4095,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 = [];
@@ -4452,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,
@@ -4537,6 +4595,7 @@ function commandSpecGaps(specs, command) {
   isPlannedStopStatus,
   isResourceKind,
   isTransformationRecord,
+  isWebhookSecretSegment,
   isoDurationHours,
   itemKeyOf,
   judgeAgainstSpec,
@@ -4599,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.13",
+  "version": "0.9.15",
   "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",