Onay entegrasyonu

Uyumluluk: Pactmark 0.2.x.

Uyguladığınız dizi

Şekil 1. Ortadaki iki şerit sizin uygulamanıza aittir. Sıralamayı doğru yaparsanız güvenlik özellikleri bedavaya gelir; yanlış yaparsanız hiçbir çalışma-zamanı zorlaması sizi kurtarmaz.

1. Bir kararın gerektiğini fark edin

Olay akışında ApprovalRequested’ı izleyin veya RunProjection.waitingDecisionId alanını okuyun:

for await (const event of runtime.events(authority, runId)) {
  if (event.eventType === "ApprovalRequested") {
    const { decisionId, decisionGateDigest, proposedEffectDigest } = event.payload;
    await queueForReview({ runId, decisionId, proposedEffectDigest });
  }
}

Olay içerik değil özet taşır. Önizlemeyi bir akış üzerinden gelen hiçbir şeye güvenmeden, kimliği doğrulanmış inceleme API’sinden çekin.

2. İnsanın gerçekten karar verebileceği bir önizleme gösterin

<DecisionPreview>
  <Field label="İşlem">{preview.operationClass}</Field>
  <Field label="Hedef">{preview.normalizedTarget}</Field>
  <Field label="Sonuç">{preview.materialConsequence}</Field>
  <Field label="Geri alınabilir">{preview.reversibility}</Field>
  <Field label="Risk sınıfı">{gate.riskClass}</Field>
  <Field label="Maliyet sınırı">{gate.costBound}</Field>
  <Field label="Politika">{gate.policyRegistrationDigest}</Field>
  <Field label="Grant">{gate.capabilityGrantId}</Field>
</DecisionPreview>

normalizedTarget’ı gösterin, modelin ham çıktısını asla. Normalize edilmiş değer gerçekte kullanılacak olandır; başka bir şey göstermek, insanın gerçekleşenden farklı bir şeyi onayladığı anlamına gelir.

3. Aktörün kimliğini şimdi doğrulayın

“Oturum var mı” değil — karar anında, bu risk sınıfı için politikanızın gerektirdiği güçle kimlik doğrulaması yapın. AuthenticationStrength ve DecisionRole yetki bağlamında taşınır ve zayıf kimlik doğrulamalı ya da yanlış rollü bir karar hiçbir şey göndermez.

4. Challenge’ı verin ve gönderin

const { challengeProof, expiresAt } = await runtime.issueDecisionChallenge(
  authority,
  runId,
  decisionId,
  createCommandContext({
    commandId: createCommandId(),
    operation: "decision.challenge",
    payload: { decisionId },
  }),
);

// Doğrudan gönderin. Saklamayın, loglamayın, bir URL'den geçirmeyin.
await runtime.approve(
  authority,
  runId,
  { decisionId, note: "OPS-4821 talebine göre incelendi" },
  createCommandContext({
    commandId: createCommandId(),
    operation: "decision.approve",
    payload: { decisionId, challengeProof },
  }),
);

Bunu asla yapmayın

Kanıtı kalıcılaştırmak, bir sorgu dizesine koymak, e-postaya eklemek, debug seviyesinde loglamak veya model bağlamına sokmak.

Bunun yerine

Tek bir istek boyunca bellekte tutun, gönderin ve başka her yerde süresinin dolmasına izin verin.

Referans nextjs-vercel fixture’ı, kanıtları tarayıcıdan gidip gelmek yerine kısa ömürlü, sunucu tarafı bir challenge kasasında tutar. Bu deseni kopyalamaya değer.

5. Reddi açıkça ele alın

await runtime.reject(
  authority,
  runId,
  { decisionId, reasonCode: "amount_above_desk_limit" },
  command,
);

ApprovalRejected bir reasonCode ve planning, failed ya da cancelled olabilen bir nextStatus taşır. Ret, kendi yolu olan birinci sınıf bir sonuçtur; bir hata değildir.

Idempotency ve tekrar

Her komut, bir commandId taşıyan bir CommandContext içerir. Aynı komutu tekrarlamak aynı semantik sonucu döndürür. Aynı kimliğe sahip ama farklı içerikli bir komut, sessizce üzerine yazmak yerine KAF_HTTP_IDEMPOTENCY_CONFLICT ile çakışır. Bu, en çok tam olarak burada önemlidir: iki kez tıklanan bir onay düğmesi iki onaya dönüşmemelidir.

KAF_COMMAND_IDEMPOTENCY_EXPIRED, idempotency ufkunun geçtiği anlamına gelir — komut güvenle tekilleştirilemeyecek kadar eskidir. Bunu “daha çok dene” değil, “insana yeniden sor” olarak değerlendirin.

Ne test edilmeli

// Onay tekrarı aynı sonucu döndürür.
// İki kez kullanılan bir kanıt reddedilir.
// Süresi dolmuş bir kanıt hiçbir şey göndermez.
// Tenant'lar arası bir onaylayan reddedilir.
// Yanlış rollü bir onaylayan reddedilir.
// Reddedilmiş bir karar sıfır-gönderim sayacı üretir.
// A etkisine bağlı bir karar B etkisini serbest bırakamaz.

Sıfır-gönderim doğrulaması önemli olandır. Bir hata fırlatıldığını doğrulamak, dış hedefin hiç çağrılmadığını doğrulamaktan zayıftır.

Hâlâ sizin sorumluluğunuzda olanlar

Pactmark kararı bağlar. İnsanın önizlemeyi anladığını, önizlemenin adil bir özet olduğunu veya politikanızdaki masa limitinin doğru sayı olduğunu güvence altına alamaz. Tehdit modeli satırı TM-05 bu artık riski açıkça kaydeder.

İnsan kararları kavramı

Bir onayın neyi bağladığı ve asla feragat edemediği sekiz şey.

İade senaryosu

Aynı akışın eksiksiz, görüşlü bir senaryodaki hâli.

Başlarken

Temel kavramlar

Rehberler

Dağıtım

Üretim

Güvenlik

Onay entegrasyonu

Uyguladığınız dizi

1. Bir kararın gerektiğini fark edin

2. İnsanın gerçekten karar verebileceği bir önizleme gösterin

3. Aktörün kimliğini şimdi doğrulayın

4. Challenge’ı verin ve gönderin

Bunu asla yapmayın

Bunun yerine

5. Reddi açıkça ele alın

Idempotency ve tekrar

Ne test edilmeli

Hâlâ sizin sorumluluğunuzda olanlar

İnsan kararları kavramı

İade senaryosu

​Uyguladığınız dizi

​1. Bir kararın gerektiğini fark edin

​2. İnsanın gerçekten karar verebileceği bir önizleme gösterin

​3. Aktörün kimliğini şimdi doğrulayın

​4. Challenge’ı verin ve gönderin

Bunu asla yapmayın

Bunun yerine

​5. Reddi açıkça ele alın

​Idempotency ve tekrar

​Ne test edilmeli

​Hâlâ sizin sorumluluğunuzda olanlar

İnsan kararları kavramı

İade senaryosu

Uyguladığınız dizi

1. Bir kararın gerektiğini fark edin

2. İnsanın gerçekten karar verebileceği bir önizleme gösterin

3. Aktörün kimliğini şimdi doğrulayın

4. Challenge’ı verin ve gönderin

5. Reddi açıkça ele alın

Idempotency ve tekrar

Ne test edilmeli

Hâlâ sizin sorumluluğunuzda olanlar