Document.hasPrivateToken() — Methode · JavaScript-Referenz

Signatur

Document.prototype.hasPrivateToken(issuer)

Beschreibung

document.hasPrivateToken() gehört zur Private State Token API (früher „Trust Tokens“). Mit ihr lässt sich über Websites hinweg ein Vertrauenssignal weitergeben, zum Beispiel „dieser Nutzer ist ein Mensch und kein Bot“, ohne den Nutzer seitenübergreifend identifizierbar zu machen. Ein Aussteller (Issuer) vergibt kryptografisch verblindete Tokens, die der Browser speichert. Andere Seiten können sie später einlösen (Redemption).

Die Methode prüft nur, ob für den übergebenen Aussteller mindestens ein Token im Token-Speicher des Browsers liegt. Wie viele es sind oder was sie enthalten, verrät sie nicht. Typischerweise ruft man sie vor einem fetch() mit der Option privateToken auf. So fordert man nur dann neue Tokens an (operation: "token-request"), wenn noch keine vorhanden sind, und löst nur dann ein Token ein (operation: "token-redemption"), wenn es eines gibt.

Das zurückgegebene Promise wird mit einem boolean erfüllt. Weil der Browser den Speicher asynchron abfragt, muss man await oder .then() verwenden. Die Methode funktioniert nur in einem sicheren Kontext (HTTPS) und in einem vollständig aktiven Dokument.

Parameter

Name	Typ	Default	Beschreibung
$issuer Pflicht	string		URL des Ausstellerservers, z. B. `"https://issuer.example"`. Es zählt nur der Origin. Er muss als vertrauenswürdig gelten (HTTPS).

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true erfüllt wird, wenn mindestens ein Token des Ausstellers gespeichert ist, sonst mit false. Bei Fehlern wird es abgelehnt (siehe Hinweise).

Beispiele

Einfache Prüfung auf vorhandene Tokens

const issuer = 'https://issuer.example';

const hasToken = await document.hasPrivateToken(issuer);
console.log(`Token von ${issuer} vorhanden:`, hasToken);

Token von https://issuer.example vorhanden: false

Tokens nur bei Bedarf anfordern

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

const ensureTokens = async () => {
  if (!('hasPrivateToken' in document)) {
    console.warn('Private State Tokens werden nicht unterstützt.');
    return false;
  }

  if (await document.hasPrivateToken(ISSUER)) {
    return true; // Es sind schon Tokens da, also keine neue Anfrage
  }

  // Neue Tokens beim Aussteller anfordern
  await fetch(`${ISSUER}/.well-known/private-state-token/issuance`, {
    privateToken: { version: 1, operation: 'token-request' }
  });

  return document.hasPrivateToken(ISSUER);
};

console.log('Tokens bereit:', await ensureTokens());

Tokens bereit: true

Token einlösen, bevor ein Formular abgeschickt wird

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

const redeemIfPossible = async () => {
  try {
    if (!(await document.hasPrivateToken(ISSUER))) {
      return null; // Kein Token vorhanden, also z. B. CAPTCHA als Ausweichlösung zeigen
    }
    const res = await fetch(`${ISSUER}/.well-known/private-state-token/redemption`, {
      privateToken: { version: 1, operation: 'token-redemption', refreshPolicy: 'none' }
    });
    return res.ok;
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
    return null;
  }
};

const ok = await redeemIfPossible();
console.log(ok === null ? 'Ausweichlösung nötig' : 'Token eingelöst');

Token eingelöst

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und bisher nur in Chromium-basierten Browsern verfügbar. Vor dem Aufruf sollte man sie per Feature-Erkennung prüfen ('hasPrivateToken' in document). Aussteller müssen außerdem bei Chrome registriert sein.
Mögliche Fehler (Ablehnung des Promise): InvalidStateError, wenn das Dokument nicht vollständig aktiv ist. TypeError, wenn issuer keine gültige URL ist oder keinen sicheren Origin (HTTPS) hat. Eine Richtlinie für Berechtigungen (Permissions Policy) kann die Nutzung in eingebetteten Frames verbieten. Deshalb den Aufruf immer mit try/catch absichern.
true heißt nur, dass ein Token vorhanden ist. Ob das Einlösen gelingt, ist damit nicht sicher, denn der Browser begrenzt, wie oft eingelöst werden darf.
Die Methode ist nicht zu verwechseln mit document.hasRedemptionRecord(). Diese prüft, ob schon ein Einlösungsnachweis (Redemption Record) existiert, nicht ob ein Token da ist.
Datenschutz: Die Zahl der Aussteller pro Top-Level-Seite ist begrenzt. Die API ist bewusst so gebaut, dass sie keine seitenübergreifende Identifikation erlaubt.

Siehe auch

Request Document Document.mozSetImageElement() TrustedScript.toJSON() Document.createTouch()