메뉴
Amankan sinkronisasi offline-online AWCMS dengan HMAC signature dan anti-replay. Gunakan saat implementasi sync push/pull, verifikasi request node, atau R2 object queue. Sesuai doc 08 & 10.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | awcms-sync-hmac |
| description | Amankan sinkronisasi offline-online AWCMS dengan HMAC signature dan anti-replay. Gunakan saat implementasi sync push/pull, verifikasi request node, atau R2 object queue. Sesuai doc 08 & 10. |
Ikuti docs/awcms/08_sop_operasional_user_guide.md dan docs/awcms/10_template_kode_coding_standard.md.
Celah lintas-tenant lama (tenant & node di luar material tanda tangan) sudah ditutup dengan skema signature ber-versi. Gunakan v2 untuk semua kode & node baru.
signature = HMAC-SHA256(secret, "v2:<tenantId>:<nodeCode>:<timestamp>:<body>")
X-AWCMS-Tenant-ID ditukar ke tenant B.X-AWCMS-Signature-Version: 2.tenantId = UUID; nodeCode &
timestamp dari HTTP header (tak boleh mengandung CR/LF); body adalah field
terakhir sehingga : di dalamnya tak menggeser batas field sebelumnya.tenantId = UUID
ditegakkan di boundary v2, bukan sekadar diasumsikan. nodeCode boleh
mengandung : (schema node_code text), jadi tanpa syarat UUID, batas
tenant/node ambigu — (tenantId="A", nodeCode="x:y") dan
(tenantId="A:x", nodeCode="y") menghasilkan material identik. UUID = 36 char
tetap tanpa : → batas tak ambigu. computeSyncSignatureV2 throw bila
tenantId bukan UUID; verifySyncSignatureV2 fail-closed (return
false). Hanya tenantId yang dibatasi; nodeCode tak disentuh dan format
material v2 TIDAK berubah → node v1/v2 lama (tenant id-nya UUID) tak
terpengaruh; mini/spec tak perlu ubah format material.domain/sync-hmac.ts
computeSyncSignatureV2 / verifySyncSignatureV2).signature = HMAC-SHA256(secret, "<timestamp>.<body>")
X-AWCMS-Signature-Version.SYNC_HMAC_ALLOW_LEGACY bukan false
(default: mengizinkan). Operator men-set SYNC_HMAC_ALLOW_LEGACY=false
setelah semua node pindah ke v2 untuk menolak v1 sepenuhnya.SYNC_HMAC_ALLOW_LEGACY=false DAN semua
node memakai v2. Jangan klaim advisory tertutup sebelum kedua syarat itu.v2 kanonik di awcms (base ini). awcms-mini dan skill/spec node harus
di-update agar node & spec mencerminkan material v2 yang persis sama sebelum
SYNC_HMAC_ALLOW_LEGACY=false diaktifkan di deployment mana pun. Idealnya
lanjutkan ke secret per-node (saran advisory ke-3) — di luar scope patch ini.
inactive + approve adminresolveOrRegisterSyncNode meng-INSERT node first-contact dengan
status='inactive' (bukan active). Node dikarantina sampai admin menyetujui
lewat PATCH /api/v1/sync/nodes/{id} (status: "active", guarded
sync_storage.node_management.update, audited). Ini menutup jalur "node-id
baru" — request palsu untuk tenant lain mendarat di node inactive dan ditolak
gate node.status !== "active". Node yang sudah active tak terpengaruh.
(Kolom sql/010 masih default active untuk baris historis; INSERT di kode
yang membuat baris baru jadi eksplisit inactive — tanpa mengedit migration
terapan.)
X-AWCMS-Tenant-ID, X-AWCMS-Node-ID, X-AWCMS-Timestamp,
X-AWCMS-Signature, X-AWCMS-Signature-Version (2 untuk v2).
SYNC_HMAC_ALLOW_LEGACY ≠ false.node.status !== "active" → 403); node baru
auto-register inactive dan wajib approve admin.awcms-idempotency.sequenceDiagram
participant N as Node
participant S as Server
N->>S: push (Tenant-ID + Node-ID + Timestamp + Signature + Signature-Version:2 + body)
S->>S: cek node aktif · verifikasi HMAC v2 (tenant+node bound) · cek skew · idempotent
S-->>N: ack + checkpoint (atau tolak)
N->>S: pull update
S-->>N: event baru
Note over N,S: Conflict high-risk → resolusi manual + audit
awcms_object_sync_queue.SYNC_HMAC_ALLOW_LEGACY=true, ditolak saat false.inactive → pull ditolak; node active tetap jalan.Triase dan perbaiki temuan CodeQL code scanning AWCMS (github.com/ahliweb/awcms/security/code-scanning). Gunakan saat diminta "analisis code scanning"/"perbaiki CodeQL", saat sebuah PR gagal check CodeQL, atau saat menemukan alert baru. Mendokumentasikan enam false-positive nyata yang sudah ditemukan (name-heuristic password, incompatible-types typeof/null, URL substring-sanitization di test mock, dua kasus dismiss resmi tanpa reformulasi kode, Bun.SQL tagged-template null-cast, dan build-time extension seam trivial-conditional) plus pola "unused-local-variable di test kadang menandai coverage gap", DAN satu counter-example trivial-conditional yang ternyata bug NYATA (dead-code fallback karena helper non-nullish, alert
Port sebuah modul/fitur yang sudah matang & teruji dari repo awcms-mini ke repo awcms secara atomic, adaptasi (bukan copy), sampai semua cek hijau + commit atomic. Gunakan saat diminta "port modul <X> dari mini", "terapkan fitur mini ke awcms", atau saat sebuah modul fondasi awcms-mini belum ada di awcms. Menegakkan kontrak alur mini-first (docs/awcms/alur-pengembangan-mini-first.md): rename prefix awcms_mini_→awcms_, penomoran migrasi lanjutan, drop dependensi/toolchain yang belum ada di awcms, dan verifikasi DoD.
Jalankan proses rilis AWCMS dengan Changesets. Gunakan saat diminta merilis versi, bump version, generate CHANGELOG, membuat tag vX.Y.Z, atau memeriksa changeset pending. Sesuai kebijakan SemVer doc 09.
BACAAN SAJA / HISTORIS (ADR-0034) — kontrak kesiapan ekstensi ERP base (`_shared/business-transaction-contract.ts`/`_shared/erp-reference-data-contract.ts`/`_shared/ports/period-lock-port.ts`) DAN jalur aplikasi-turunan yang skill ini asumsikan SUDAH DIHAPUS. ERP kini dibangun sebagai modul `domain` LANGSUNG di `src/modules/` (pola sama modul base lain), bukan repo turunan; file kontrak & fixture `example-erp-extension` yang dirujuk tidak lagi ada. Rujukan historis dari Issue
Audit dan perkuat backend & integrasi eksternal AWCMS (resiliensi, outbox, webhook/provider, versioning API, observability). Gunakan saat menambah/mengeraskan integrasi ke provider luar (R2, WhatsApp, email, AI, pajak), memperbaiki keandalan delivery, atau menaikkan ketahanan backend. Menegakkan ADR-0006 (provider opsional, di luar transaksi) dan pola outbox doc 16.
Scaffold modul baru pada modular monolith AWCMS. Gunakan saat membuat modul domain baru di src/modules/ (mis. warehouse-management, accounting-tax) atau saat memerlukan struktur module.ts + domain/application/infrastructure/api + README. Ikuti struktur standar doc 10 & 11.