Passes

passes turns a booking into a ticket and a resource into something people can walk into. You issue a pass, sign a token for it with the signing-keys block, and put the token in a QR code or on an NFC tag. At the door a scanner verifies the signature against your JWKS and the database checks the pass in: once for a ticket, as often as the pass allows otherwise, and only while there is a free seat.

better-supabase add passes

import { createPasses } from "better-supabase/blocks/passes";

The module requires tenant and access. With bookings a pass can be a ticket for a booking or a pass for a resource, with outbox its events are recorded, and with audit issuing and revoking are audited. Scans are logged in the module's own table instead of the audit log. Signing needs the signing-keys block in the app; the module itself never reads a key (see ADR 0073).

TablesCopy Anchor Link

Both tables are read through the functions only. The holder reads their own passes with the nonce; members with passes.read list the organization's.

Issue a passCopy Anchor Link

const passes = createPasses({ transport, tenant: organizationId });

const ticket = await passes
  .issue({ bookingId, holderUserId: userId, holderName: "Jane" })
  .orThrow();

A pass for a booking is a ticket: it is valid until the booking ends and admits once, unless validUntil or usesAllowed say otherwise. A pass for a resourceId (a gym, a venue, a meeting room) admits as many times as usesAllowed allows, or without a limit when it's missing. A pass can also name any record in config.subjects, such as an event or a membership, with subject. kind is free text such as ticket, membership or visitor. Issuing needs passes.manage.

The passes section lists a record's passes on its page, with issue and revoke writes.

Sign the tokenCopy Anchor Link

Signing runs on the server with the organization's key:

const passes = createPasses({
  transport,
  tenant: organizationId,
  signer: signingKeys.signer(
    { type: "organization", id: organizationId },
    { create: "Ed25519" },
  ),
});

const pass = await passes.get(passId).orThrow();
const token = pass && (await passes.token(pass).orThrow());

The token is a compact JWS with typ: "vnd.pass+jwt" (PASS_TOKEN_TYPE), so another kind of token can't be replayed as a pass. Its claims are the pass id (sub), the nonce (jti), the organization (org), kind, the holder's name, and nbf and exp. A token expires with the pass, or after tokenLifetime (30 days) for a pass that runs longer; sign a new one when the holder opens their wallet. The exp keeps the signing key in the JWKS until the token expires, so rotating the key doesn't strand it.

Render the token with any QR library, or write it to an NFC tag as a text record. The block doesn't ship one, so the app picks the library.

Check inCopy Anchor Link

const door = createPasses({
  transport,
  jwks: () => fetch(`${origin}/.well-known/jwks.json`).then((r) => r.json()),
});

const scan = await door
  .checkIn(scanned, { gate: "north", resourceId: roomId })
  .orThrow();

if (!scan.admitted) {
  showRejection(scan.reason);
}

checkIn verifies the signature and the exp first: a token that fails comes back as an error (PASS_TOKEN_INVALID or PASS_TOKEN_EXPIRED) and never reaches the database. The database then compares the nonce and decides, under a row lock on the pass. Every scan is logged, and an admitted one uses the pass once. Checking in needs passes.check_in.

A ticket opens checkInOpens (one hour) before its booking starts. A pass for a resource without a booking is a drop-in: it is admitted only while the confirmed bookings, live holds and drop-ins on the resource are fewer than its capacity. A drop-in counts for dropInLength (two hours) after it was admitted. An advisory lock per resource keeps two scans at once from taking the last seat twice.

blocks: {
  passes: { options: { checkInOpens: "30 minutes", dropInLength: "90 minutes" } },
},

Class creditsCopy Anchor Link

Turn on credits to sell a pack of classes: a pass with usesAllowed and no booking of its own pays one credit for each class its holder books. The option is off by default and needs the bookings block.

blocks: {
  passes: { options: { credits: true, creditRefundBefore: "12 hours" } },
},

const pack = await passes
  .issue({ holderUserId: userId, resourceId, usesAllowed: 10 })
  .orThrow();

const booked = await passes
  .bookWithCredit(pack.id, { serviceId, resourceId, startsAt })
  .orThrow();

booked.creditsLeft; // 9

bookWithCredit books a confirmed booking for the holder, through the bookings block's slot check and exclusion constraint, and takes one credit in the same transaction. Every credit is a row in pass_credit_entries: -1 for a booking and +1 for a refund, and the pass's uses is their running total, so credits(passId) returns the whole history, newest first. The holder books with their own pass; a member with passes.manage can book for them.

Cancelling the booking at least creditRefundBefore (default 12 hours) before it starts gives the credit back once; a later cancellation keeps it. Rescheduling keeps the credit with the booking. At the door, issue a ticket for the booking and scan that: scanning the pack itself counts as another use.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

pass.issued and pass.revoked, pass.admitted and pass.rejected for every scan, and pass.credit_used and pass.credit_refunded for class credits. The events page lists their payloads.