Document.hasRedemptionRecord() — Methode · JavaScript-Referenz

Signatur

Document.prototype.hasRedemptionRecord(issuer)

Beschreibung

document.hasRedemptionRecord() gehört zur Private State Token API (früher „Trust Tokens“). Mit dieser API kann ein Aussteller (Issuer) einem Browser kryptografisch abgesicherte Tokens ausstellen, zum Beispiel nachdem ein Nutzer als vertrauenswürdig erkannt wurde, etwa durch ein Login oder eine bestandene Bot-Prüfung. Später kann eine andere Website diese Tokens einlösen (Redemption). Dabei entsteht ein Redemption Record (RR), den der Browser für diese Website speichert und bei weiteren Anfragen mitsenden kann.

Die Methode fragt ab, ob für die aktuelle Top-Level-Website schon ein solcher Redemption Record vom angegebenen Aussteller vorliegt. Das Promise wird mit true oder false erfüllt. Typischerweise rufen Sie die Methode vor einer Einlösung per fetch() mit der Option privateToken: { operation: "token-redemption" } auf. So vermeiden Sie unnötige Einlösungen, denn die Anzahl der Einlösungen ist vom Browser begrenzt. Ist schon ein Record vorhanden, können Sie ihn gleich mit operation: "send-redemption-record" weiterreichen.

Verwandt ist document.hasPrivateToken(issuer). Diese Methode prüft, ob überhaupt noch nicht eingelöste Tokens dieses Ausstellers vorliegen. hasRedemptionRecord() prüft dagegen nur, ob eine Einlösung bereits stattgefunden hat. Die Aufrufe dürfen nur in einem sicheren Kontext (HTTPS) erfolgen. Außerdem muss die Permissions Policy private-state-token-redemption die Nutzung für das Dokument erlauben.

Parameter

Name	Typ	Default	Beschreibung
$issuer Pflicht	string		URL des Token-Ausstellers, z. B. `"https://issuer.example"`. Ausgewertet wird nur der Origin. Er muss potenziell vertrauenswürdig sein, also HTTPS (oder localhost) verwenden.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true erfüllt wird, wenn für die aktuelle Top-Level-Website ein Redemption Record dieses Ausstellers vorliegt, sonst mit false. Das Promise wird abgelehnt: mit TypeError bei ungültiger oder unsicherer Issuer-URL, mit InvalidStateError, wenn das Dokument nicht vollständig aktiv ist, und mit NotAllowedError, wenn die Permissions Policy den Zugriff verbietet.

Beispiele

Einfache Prüfung auf einen vorhandenen Redemption Record

const ISSUER = "https://issuer.example";

const pruefen = async () => {
  if (!("hasRedemptionRecord" in document)) {
    console.log("Private State Tokens werden nicht unterstützt");
    return;
  }
  const vorhanden = await document.hasRedemptionRecord(ISSUER);
  console.log("Redemption Record vorhanden:", vorhanden);
};

pruefen();

Redemption Record vorhanden: false

Nur einlösen, wenn noch kein Record existiert

const ISSUER = "https://issuer.example";

const sicherstellenRecord = async () => {
  if (await document.hasRedemptionRecord(ISSUER)) {
    return true; // bereits eingelöst – kein erneuter Verbrauch eines Tokens
  }
  if (!(await document.hasPrivateToken(ISSUER))) {
    console.log("Keine Tokens dieses Ausstellers vorhanden");
    return false;
  }
  // Token beim Aussteller einlösen; der Browser speichert den Record
  await fetch(`${ISSUER}/redeem`, {
    privateToken: {
      version: 1,
      operation: "token-redemption",
      refreshPolicy: "none"
    }
  });
  return document.hasRedemptionRecord(ISSUER);
};

sicherstellenRecord().then((ok) => console.log("Vertrauenssignal verfügbar:", ok));

Vertrauenssignal verfügbar: true

Record an den eigenen Server weitergeben (z. B. Betrugserkennung)

const ISSUER = "https://issuer.example";

const bestellungAbsenden = async (bestellung) => {
  const init = {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(bestellung)
  };

  try {
    if (await document.hasRedemptionRecord(ISSUER)) {
      init.privateToken = {
        version: 1,
        operation: "send-redemption-record",
        issuers: [ISSUER]
      };
    }
  } catch (err) {
    // z. B. NotAllowedError durch Permissions Policy
    console.warn("Record-Prüfung fehlgeschlagen:", err.name);
  }

  const res = await fetch("/api/bestellung", init);
  console.log("Status:", res.status);
};

bestellungAbsenden({ artikel: "A-42", menge: 1 });

Status: 200

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell und nur in Chromium-basierten Browsern (Chrome, Edge) verfügbar. Firefox und Safari unterstützen sie nicht. Prüfen Sie daher immer vorab mit "hasRedemptionRecord" in document.
Sicherer Kontext & Permissions Policy: Die Methode funktioniert nur unter HTTPS. In iframes muss die Einbettung die Policy private-state-token-redemption erlauben, zum Beispiel über allow="private-state-token-redemption". Sonst wird das Promise mit NotAllowedError abgelehnt.
Nicht mit hasPrivateToken() verwechseln: hasRedemptionRecord() sagt nichts darüber aus, ob noch Tokens übrig sind. Es meldet nur, ob schon eine Einlösung stattgefunden hat.
Begrenzte Einlösungen: Der Browser begrenzt, wie oft Tokens eingelöst werden dürfen (Rate-Limit pro Website und Aussteller). Prüfen Sie deshalb vor jeder Einlösung zuerst mit dieser Methode, ob schon ein Record vorliegt. Ein Record kann außerdem ablaufen. Mit refreshPolicy: "refresh" erzwingen Sie eine neue Einlösung.
Datenschutz: Das Ergebnis ist bewusst nur ein einzelnes Bit (vorhanden / nicht vorhanden), damit sich Nutzer darüber nicht website-übergreifend verfolgen lassen. Wie vertrauenswürdig der Record ist, muss Ihr Server anhand der Signatur des Ausstellers prüfen, nicht der Client.

Siehe auch

Request Document new IdentityCredentialError() Document.adoptNode() Document.getSelection()