MyJackfruit

Help
Browse topics · Sign-in and tokens

Sign-in and tokens

← Back to How does a profile picture (face) work?

How do I make a DPoP proof for each request?

Short answer

Make a key pair, write the proof's header and claims, sign them with the private key, and send the proof beside the token.

Before you start

Your app can make ECDSA P-256 signatures, for example with WebCrypto in a browser or in Node.js.

Words used here (2)
sign-in token
A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Make a key pair.

    Make an ECDSA key pair on the P-256 curve and keep the private half in memory only, never in localStorage or on disk.

    More about this

    A key pair is two matching keys: your app signs with the private one and sends the public one when it gets its token. The platform binds the token to that public key and writes its thumbprint, a short hash of the key, into the token as cnf.jkt. For a sign-in token, send the public half as dpopJwk with the code; for a machine token, the proof on the token request carries it. Sign every proof for that token with the same key: another key answers 401 DPoP proof key does not match the token's bound key (cnf.jkt). The sign-in kit's generateDpopKeyPair makes such a key, and its dpopHeaders does steps 2 to 5 for you.

  2. Write the proof's header.

    Write the header as JSON with typ dpop+jwt, alg ES256 and jwk, the public half of your key: kty, crv, x and y.

    More about this

    A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449), made as a JWT, a signed JSON web token. ES256, ECDSA on P-256 with SHA-256, is the only algorithm the platform takes, for proofs and for its own tokens. On a call with a token, a header with another typ or alg, or with no jwk, answers 401 with a message that starts Invalid DPoP proof.

  3. Write the proof's claims.

    Write htm, the request's method; htu, its address without query or fragment; iat, the time now in whole seconds; and jti, a new unique id.

    More about this

    htu starts with https:// and the host the request goes to: https://id.gilb.com to get a machine token, renew a sign-in, sign out or make a vault, and the vault's own host, such as https://<name>.gilb.com, for its records. A wrong host answers 401 DPoP proof htu does not match the request URI, a wrong method 401 DPoP proof htm does not match the request method, and an iat more than 60 seconds from the platform's clock 401 DPoP proof iat is outside the freshness window. When the request carries a token, you may add ath, the SHA-256 hash of the token in base64url, bytes written as letters and digits that are safe in a web address; it must then match. A request with no token, such as a renewal, must have no ath.

  4. Sign it with the private key.

    Join the base64url header and the base64url claims with a dot, sign that text with the private key, and add the base64url signature after a second dot.

    More about this

    The signature is the raw 64 bytes, r then s. WebCrypto's ECDSA sign gives that form; some others, such as iOS SecKeyCreateSignature, give DER, which must be turned into the raw form first. The result is the proof, one line of text.

  5. Send the proof beside the token.

    Send the proof in the DPoP header, with Authorization: DPoP followed by the token, and make a new proof for every request, retries too.

    More about this

    A proof works once: sent again it answers 401 DPoP proof has already been used (replay rejected), and a proof with no jti answers 401 DPoP proof has no jti (replay protection requires it). A token sent with no proof is refused, or the call is treated as coming from no one. A request for a machine token, a renewal and a trade for an outside service carry a proof too, in the DPoP header alone.

Deeper

The platform checks, in this order: the token's signature, issuer and audience; the proof's signature against the key inside it; that this key is the token's key; for a person's sign-in token, that the person has not signed out; method, address and time; ath when it is there; and last, that the jti is new. A failed check answers 401 with error Unauthorized and a message that names it, and does not use up the jti. On the token request for a machine token, a wrong header, signature, method, address or time answers 400 invalid_request; that request's proof is not checked for reuse. On a renewal every fault answers 401 renewal refused.

The e-mail-code sign-in itself, POST https://id.gilb.com/base/auth/email/verify-code, takes no proof: the public key goes in its body as dpopJwk.

To check a token the platform made, use its public keys, with no sign-in, at https://id.gilb.com/base/auth/jwks.json. It is a JWKS, a JSON Web Key Set: a list of public keys, each with a key id (kid). The same set is at https://id.gilb.com/.well-known/jwks.json. A cache may keep it 300 seconds. Your app needs it only to check a token, not to make a proof.

The full reference, with every field and every answer, is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.SignIn, https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88. Its exhibits Proof and ProofChecks hold the checks and the answers. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/auth/dpop.ts:10-33 (TOKEN_ALG ES256, DPOP_TYP dpop+jwt, canonicalHtu drops query and fragment); src/auth/verify.ts:76-79 (60 s iat window), :144-152 (DPoP proof iat is outside the freshness window), :167-178 (DPoP proof has no jti (replay protection requires it), DPoP proof has already been used (replay rejected); jti consumed last), :355-490 (the order: token, cnf.jkt, proof signature with its own jwk, typ, DPoP proof key does not match the token's bound key (cnf.jkt), assertSignInLive, htm, htu, iat, ath when present, jti), :406-412 (Invalid DPoP proof: ...); src/auth/principal.ts:118-120 (htu = https:// + resolved host + path), :145-158 (DPoP scheme with no proof header: empty proof, refused; Bearer scheme: anonymous); src/auth/bearer-principal.ts:161-200 (key-bound token with no proof refused on /lws and /files); src/auth/dpop-nonce.ts:143-208 (proof with no token, as on the renewal: no ath allowed, DPoP proof must not carry ath); src/auth/machine-token.ts:272-312 (token request proof); src/routes/email-auth.ts:92-103 (dpopJwk in the body, no proof); src/auth/issue.ts:73, :78 (cnf.jkt = RFC 7638 thumbprint); src/routes/jwks.ts:125-133 (max-age, both paths); public read https://id.gilb.com/base/auth/jwks.json 2026-11-11: 200, cache-control public, max-age=300. gilb-signin 0.3.0 (npm latest, read https://registry.npmjs.org/gilb-signin 2026-11-11; gitHead d7682177 = tag v0.3.0; code read at d7682177): src/dpop.ts:84-95 (non-extractable P-256 key), :104-107 (htuFor), :118-137 (header alg ES256, typ dpop+jwt, jwk; claims jti, htm, htu, iat, ath when a token is given), :149-167 (raw 64-byte r||s; DER from iOS SecKeyCreateSignature must be converted), :179-189 (dpopHeaders). Dev.Guide.SignIn (A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88; read for agreement, not copied) Proof, ProofChecks, WhichHost, KeySafety. The example dpop-proof.ts is written here from RFC 9449 and the checks above, placeholders only.: src/auth/machine-token.ts:272-312 (verifyTokenRequestProof checks typ, alg, jwk, signature, htm, htu and iat only, each failure 400 invalid_request) and src/auth/dpop-nonce.ts:143-152 (the token-request proof's jti is not used up and ath is not read; no token on that request, so no signed-out check).: POST /base/auth/email/verify-code and POST /base/client/register take no proof, so the htu host list names only the id.gilb.com calls that carry one (machine token, renewal, sign-out, create-named). Rows: Developer.DpopProofPerRequest, PublishedSigningKeys, Security.TokenBoundToYourKey.

For developers

TypeScript

dpop-proof.ts

// One DPoP proof for one request (RFC 9449), with WebCrypto only.
const enc = new TextEncoder();
const b64url = (bytes: Uint8Array) =>
  btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

// Make the key pair once. The private half cannot be copied out of WebCrypto.
export async function makeKey() {
  const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, ["sign", "verify"]);
  const { kty, crv, x, y } = await crypto.subtle.exportKey("jwk", pair.publicKey);
  return { publicJwk: { kty, crv, x, y }, privateKey: pair.privateKey }; // send publicJwk as dpopJwk
}

// A new proof for every request, retries too.
export async function dpopProof(
  key: { publicJwk: object; privateKey: CryptoKey },
  method: string,
  url: string,
  token?: string,
) {
  const u = new URL(url);
  const header = { typ: "dpop+jwt", alg: "ES256", jwk: key.publicJwk };
  const claims: Record<string, unknown> = {
    htm: method.toUpperCase(),
    htu: `https://${u.host}${u.pathname}`, // no query, no fragment
    iat: Math.floor(Date.now() / 1000),
    jti: crypto.randomUUID(),
  };
  if (token) claims.ath = b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(token))));
  const input = `${b64url(enc.encode(JSON.stringify(header)))}.${b64url(enc.encode(JSON.stringify(claims)))}`;
  const sig = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key.privateKey, enc.encode(input));
  return `${input}.${b64url(new Uint8Array(sig))}`; // WebCrypto gives raw r||s, 64 bytes
}

// Use:
// const url = "https://<name>.gilb.com/lws/r/<record id>";
// await fetch(url, { headers: { Authorization: `DPoP ${token}`, DPoP: await dpopProof(key, "GET", url, token) } });

Checked against GilbApp d529620.