@mythryl/server-sdk

Server-side SDK for Mythryl mini apps. It verifies the token an app receives from sdk.auth.signin(), so your server knows who the player is, and the webhooks Mythryl sends it.

npm install @mythryl/server-sdk

import { createVerifier } from "@mythryl/server-sdk";

// Once, at startup. The audience is your app's domain.
const mythryl = createVerifier({ audience: "my-game.example" });

// On each request that carries a token.
const authorization = request.headers.get("authorization");
const { did } = await mythryl.verifyAuthorization(authorization);

did is the player's identity, for example did:plc:abc123.

What is checked

verify and verifyAuthorization check the signature against Mythryl's published keys (EdDSA only), the token type, the issuer, the audience and the expiry. The keys are fetched from https://mythryl.app/.well-known/jwks.json on first use, cached, and fetched again when a token names a key that is not cached. Create one verifier and reuse it so the cache is shared.

API

createVerifier(options)

| Option | Description | | --- | --- | | audience | Your app's domain, or a list of domains. A token issued for another domain is rejected. Required. | | issuer | Expected issuer. Default https://mythryl.app. | | jwksUrl | Location of the key set. Default: the issuer's /.well-known/jwks.json. | | keys | A fixed key set to use instead of fetching one. For tests and offline use. | | clockTolerance | Tolerance for clock difference between servers, in seconds. Default 5. | | keyCooldown | Minimum time in milliseconds between key set fetches. Default 30000. |

It returns a verifier with:

• verify(token): verifies a token string.
• verifyAuthorization(header): verifies the token in an Authorization: Bearer <token> header value.

Both resolve with { did, audience, issuedAt, expiresAt, tokenId }.

• verifyWebhook({ body, signature }): verifies a webhook request and resolves with the event.

Webhooks

Mythryl signs each request to your webhookUrl. Pass the raw body (not parsed and re-serialised) and the Mythryl-Signature header:

const body = await request.text();
const signature = request.headers.get("mythryl-signature");
const event = await mythryl.verifyWebhook({ body, signature });
// { id, type, createdAt, appId, did, data }

The signature is checked like a token (key, type, issuer, audience, expiry of 5 minutes) and must be for exactly this body. Delivery is at least once, so de-duplicate by event.id, and use createdAt for order.

bearerToken(header)

Extracts the token from an Authorization header value, or returns undefined.

Errors

A rejected token throws a TokenError. code gives the reason and status the HTTP status to answer with: 503 for keys_unavailable, otherwise 401.

| Code | Meaning | | --- | --- | | missing | No token was supplied. | | malformed | The value is not a well-formed token, or its claims are not valid. | | invalid_signature | The signature does not verify, or no published key matches. | | expired | The token has expired. | | wrong_issuer | The token was issued by a different issuer. | | wrong_audience | The token was issued for a different app. | | wrong_type | The token is not the kind expected: an app token is not a webhook signature, nor the reverse. | | body_mismatch | A webhook signature is not for the body received. | | keys_unavailable | The published keys could not be fetched. |

import { TokenError } from "@mythryl/server-sdk";

try {
  await mythryl.verifyAuthorization(authorization);
} catch (error) {
  if (!(error instanceof TokenError)) throw error;
  return new Response(error.message, { status: error.status });
}

Key rotation

Mythryl rotates its signing keys, and a new key signs from the moment it is created. A verifier that fetched the key set within the last keyCooldown rejects tokens signed with the new key as invalid_signature until the cooldown ends, then fetches the new set.

License

MIT