DEV Community: Zurox

The Browser Is Not the Source of Truth: Signing a Calculation Context in Next.js

Zurox — Fri, 31 Jul 2026 09:02:10 +0000

A client-side preview is often the right product choice. A person can see a result immediately, decide whether it is useful, and only then choose to pay for a longer report.

It is the wrong place to establish the facts that a paid workflow will fulfill.

I ran into this while building AstroZen, a Next.js application with a free calculated chart and an optional paid Dossier. The browser needs the calculation context to render the preview. But if checkout accepts that context as truth, a modified browser request can change the data attached to the paid order.

The pattern I used is small:

validated input
  -> server calculation
  -> context + HMAC signature
  -> browser preview
  -> checkout verifies the same context + signature
  -> server persists an immutable order intent

The important distinction is that the signature proves integrity. It does not turn a browser into a trusted system, authorize payment, or solve every replay problem.

Key takeaway: Integrity proves the context was not tampered with. It does not establish freshness, authorization, or payment status on its own.

The problem is not the UI

The free preview returns a structured object that is useful to show in the browser. It contains the facts a longer report will later use: normalized input, chart outputs, calculation metadata, and explicit limitations.

An early design could send that object straight from the browser to a payment endpoint:

await fetch("/api/checkout-intent", {
  method: "POST",
  body: JSON.stringify({ email, context }),
});

That is convenient, but context is now untrusted input. A user can alter it in DevTools, replay a request, or use a script that never rendered the preview at all. Client-side validation and a disabled button do not change that.

For a paid calculation, the server should establish the context once and later reject any client-supplied version that does not match it.

Sign the server result, not the raw form

AstroZen calculates its DossierContext on the server. The calculation route then returns the result and an HMAC over the exact context:

// src/lib/server/context-signature.ts
import crypto from "node:crypto";

function signingSecret(): string {
  const secret = process.env.INTERNAL_QUEUE_SECRET;
  if (!secret || secret.length < 32) {
    throw new Error("Calculation signing secret is unavailable");
  }
  return secret;
}

export function signContext(context: DossierContext): string {
  return crypto
    .createHmac("sha256", signingSecret())
    .update(JSON.stringify(context))
    .digest("base64url");
}

The route returns both values:

// src/app/api/calculate/route.ts
const result = await calculateDossier(input);

return Response.json({
  ...result,
  contextSignature: signContext(result.context),
});

The browser can render result.context, but it cannot produce a valid signature for a changed context. At checkout, the server recomputes the HMAC and compares it in constant time:

export function verifyContext(
  context: DossierContext,
  supplied: string,
): boolean {
  if (!supplied) return false;

  const expected = signContext(context);
  const left = Buffer.from(expected);
  const right = Buffer.from(supplied);

  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

If verification fails, checkout stops and asks the client to calculate again. A context with a changed time zone, item, or calculated field is rejected before an order is created.

Serialization is part of the contract

An HMAC signs bytes, not an abstract JavaScript object. In the example above, those bytes come from JSON.stringify(context).

That is acceptable for this narrow round trip because the server generates the object, the browser sends the same JSON structure back, and the route does not rely on a language-neutral signature format. It is still a contract worth treating carefully.

For a wider system, I would make the signed payload explicit:

Add a schema version to the payload.
Use canonical JSON or a typed encoding if another runtime will verify it.
Sign only the fields checkout needs, rather than an ever-growing display object.
Add an expiry and check it on the server if a calculation should only be purchasable for a limited time.

The last point matters in this implementation. The calculation context includes a generation timestamp, but the signature alone does not enforce an expiration. Integrity is not freshness.

Recompute pricing and consent on the server

Valid context does not mean that every other checkout field is trusted.

The checkout route validates the email format and the required consent fields, then decides the price tier from the server's own order history:

// src/app/api/checkout-intent/route.ts
const hasPaidOrder = await hasUsedIntroductoryPrice(supabase, email);
const pricing = pricingForPaidHistory(hasPaidOrder);

if (pricing.tier === "standard" && body.acceptStandardPrice !== true) {
  return Response.json(
    { error: "The introductory price has already been used." },
    { status: 409 },
  );
}

The browser can acknowledge a price change, but it does not choose the amount or payment-provider product ID. Those values come from server configuration after the signed calculation context has passed verification.

This is the boundary I want in any paid flow:

Client may provide	Server must decide
Email and consent selections	Price, currency, and product ID
A previously signed calculation context	Whether that context is intact
A request to start checkout	The order ID and payment session

Persist an intent before redirecting away

Payment providers require a redirect or hosted checkout session. Before creating it, the server creates an order in its database with a fresh request ID, the verified context, expected product, expected amount, currency, and the consent record.

// src/app/api/checkout-intent/route.ts
const requestId = crypto.randomUUID();

const { data: order, error } = await supabase
  .from("orders")
  .insert({
    request_id: requestId,
    email,
    context: body.context,
    status: "pending",
    expected_product_id: expectedProductId,
    expected_amount: expectedAmount,
    expected_currency: "USD",
  })
  .select("id")
  .single();

The payment provider receives the opaque requestId, not the whole calculation payload. After payment, the webhook verifies its own provider signature and checks that the completed checkout matches the stored order's expected product, amount, and currency.

That gives the webhook an independent server-side record to compare against. The success page is then a display surface, not proof of payment.

Treat delivery links as credentials

The redirect needs a way to show the completed order without exposing a permanent database identifier. I generate a random access token, store only an HMAC of that token, and attach the raw token to the success URL.

// src/lib/order-access.ts
const rawToken = `az_v${version}_${crypto
  .randomBytes(32)
  .toString("base64url")}`;

const tokenHash = crypto
  .createHmac("sha256", pepperFor(version))
  .update(rawToken)
  .digest("hex");

The database never needs the raw token. On a download request, the server hashes the submitted token with the matching pepper version, checks that stored hash, verifies expiration and revocation state, and then issues a short-lived storage URL.

This also makes key rotation practical: token versions select the correct pepper while a newer version becomes the default for new links.

What the HMAC does not solve

It is tempting to call a signed JSON object “secure” and stop there. That would hide important remaining controls.

An HMAC does not by itself provide:

Authorization. The checkout route still needs to decide which user action is allowed and which price applies.
Freshness. A signature without a verified expiry can remain valid longer than intended.
Replay prevention. The route needs rate limits, idempotency rules, or one-time server records when repeated use matters.
Payment proof. Only a verified provider webhook plus the stored intent establishes a completed purchase.
Schema safety. A display-model change can invalidate a naive serialization scheme if the signing contract is not versioned.

This app has request-size limits, and its endpoints apply IP-based rate limits when Upstash is configured. Each checkout also creates a fresh server-side order intent. I would add a server-checked expiry to the signed context before relying on the signature for a time-sensitive offer.

Test the boundary, not only the happy path

The useful test is not “does signing return a string?” It is “does a tiny change to the context make checkout refuse it?”

const context = {
  meta: { generatedAt: "2026-07-17T00:00:00.000Z" },
  birth: { timezone: "Europe/Madrid" },
} as DossierContext;

const signature = signContext(context);
expect(verifyContext(context, signature)).toBe(true);

const modified = structuredClone(context);
modified.birth.timezone = "Asia/Shanghai";
expect(verifyContext(modified, signature)).toBe(false);

At minimum, add tests for failed consent, invalid email, price-tier changes, malformed payloads, webhook signature failures, and mismatched provider amounts. These are all places where a polished client can otherwise hide an incomplete backend boundary.

The reusable idea

When a browser needs a rich preview but a later paid operation depends on that preview, do not make the browser the authority. Have the server calculate the business-critical context, sign the exact payload it is willing to accept, verify it when the client returns, and persist the order intent before handing control to a payment provider.

Keep the rest of the security model separate: server-side pricing, verified payment events, scoped delivery credentials, expiration, rate limiting, and tests for changed inputs. The HMAC is a useful link in that chain, not the chain itself.

I work on AstroZen. This post describes an engineering pattern from the product; AstroZen's astrology features are for entertainment and personal reflection.

The Hard Part of a Global Birth-Chart Calculator Was Time

Zurox — Wed, 22 Jul 2026 03:33:51 +0000

A birth-chart form looks simple: ask for a date, time, and place, then calculate.

The interface may be simple. The input is not.

1992-11-01 01:30 does not identify one universal instant. It is a wall-clock reading that only becomes meaningful after you resolve the place, the historical time-zone rule, and any daylight-saving transition. If the time is unknown, inventing a convenient default can create chart features that were never supported by the user’s data.

I ran into these problems while building AstroZen, a Next.js application that calculates a BaZi Four Pillars chart and a Western natal chart before generating an optional interpretation.

The most important architectural decision was this:

Calculation is an evidence pipeline. Interpretation is a separate layer.

This post explains the calculation pipeline, the failure modes I had to remove, and why “unknown” must remain unknown.

1. A city name is not a coordinate

Early prototypes often use a short city list or a default coordinate. That works for a layout demo, but it is not acceptable once location affects the result.

Names are ambiguous:

Paris can mean France or Texas.
Springfield needs a state or region.
Country abbreviations come in several forms.
A valid city must resolve to both coordinates and a time-zone identifier.

AstroZen sends the submitted city to Open-Meteo’s geocoding service, then scores the returned candidates against the requested country and optional region hint. It keeps the following structured result:

type ResolvedPlace = {
  name: string;
  region: string | null;
  country: string;
  countryCode: string;
  latitude: number;
  longitude: number;
  timeZone: string; // IANA, for example "Europe/Madrid"
};

Candidate selection considers exact city-name matches, country matches, an optional region hint, and population as a small tie-breaker. Population never replaces the country check.

The more important rule is what happens when resolution fails:

if (!selected || !countryMatches(selected, requestedCountry)) {
  throw new Error(
    "We could not match that city and country. Add a state or region."
  );
}

There is no silent fallback to a famous city. A visible error is better than a polished chart calculated for the wrong place.

2. A time zone is not a fixed UTC offset

Storing UTC+1 is not enough. The same location may use different offsets across seasons and historical periods. Governments also change their rules.

The geocoder therefore returns an IANA identifier such as America/New_York, not just an offset. The server converts the submitted civil time to UTC using that zone and the runtime’s time-zone database.

A simplified version of the conversion looks like this:

function zonedTimeToUtc(input: CivilTime, timeZone: string): Date {
  const guess = new Date(Date.UTC(
    input.year,
    input.month - 1,
    input.day,
    input.hour,
    input.minute
  ));

  const offsetMinutes = getOffsetFromIntl(timeZone, guess);
  return new Date(guess.getTime() - offsetMinutes * 60_000);
}

This is already safer than accepting a browser-supplied offset. It also reveals an edge case that every global date-time application should test explicitly: daylight-saving gaps and folds.

During a spring transition, some local times never occur. During an autumn transition, one wall-clock time may occur twice. An IANA zone gives you the rules, but the product still needs a declared policy for ambiguous or nonexistent local times. A date picker cannot make that decision for you.

3. UTC conversion and true solar time solve different problems

The Western chart needs a UTC instant and geographic coordinates. The BaZi calculation in AstroZen also applies a declared true-solar-time strategy before establishing the Four Pillars.

These are separate transformations.

The longitude correction is based on the difference between the birthplace longitude and the standard meridian for the local offset:

longitude correction (minutes)
  = (birthplace longitude - standard meridian) × 4

The pipeline then adds an equation-of-time correction and applies the total minute shift with full date rollover. That rollover matters: a correction near midnight can move the effective local solar time into the previous or next day.

const standardMeridian = offsetMinutes / 4;

const solarTime = resolveTrueSolarDateTime(
  civilBirthTime,
  place.longitude,
  standardMeridian
);

This is a methodology choice, not an invisible truth. Different BaZi lineages can use different boundary conventions, especially around late-night births. The application therefore records the clock time, corrected solar time, longitude, correction in minutes, and any day rollover so the result can be reviewed.

4. Planet positions should not be browser approximations

For the Western layer, I replaced lightweight orbital approximations with Swiss Ephemeris compiled to WebAssembly.

The server calculates:

geocentric tropical planetary longitudes;
retrograde state from longitude speed;
Placidus house cusps;
Ascendant and Midheaven;
major aspects with declared orb limits.

The WASM package is loaded only on the server and cached after initialization:

let ephemeris: SwissEph | null = null;
let initialization: Promise<SwissEph> | null = null;

async function getEphemeris() {
  if (ephemeris) return ephemeris;
  if (initialization) return initialization;

  initialization = (async () => {
    const { default: SwissEph } = await import("swisseph-wasm");
    const instance = new SwissEph();
    await instance.initSwissEph();
    ephemeris = instance;
    return instance;
  })();

  return initialization;
}

Lazy initialization helps with serverless cold starts, but WASM deployment adds its own failure mode: the binary must actually be present in the production bundle. A build that passes TypeScript can still fail at runtime if the .wasm asset is missing. Production-like deployment tests are essential.

5. “Unknown birth time” is not 12:00 PM

Many chart applications ask for a birth time but quietly substitute noon when it is missing. Noon is useful as an internal date reference because it is far from a day boundary. It is not evidence that the person was born at noon.

AstroZen uses local noon only as a neutral calculation reference, then removes every output that depends materially on the unknown time.

For BaZi, unknown-time mode omits:

the Hour Pillar;
Hour-dependent stem and branch relationships;
Zi Wei Dou Shu;
Dayun start timing where the boundary cannot be supported.

For the Western chart, it omits:

the Moon;
Ascendant and Midheaven;
all houses;
time-sensitive aspects;
the sidereal/Vedic validation snapshot.

The remaining result is explicitly labeled as date-based. The internal noon reference is recorded as a limitation, not shown as the user’s birth time.

This led to a general rule I now use beyond astrology software:

A fallback may keep a pipeline running, but it must not manufacture confidence in the output.

6. The browser should not own the paid calculation

Another tempting shortcut is to calculate in the browser and send the finished chart to checkout. That makes the interface responsive, but it also lets a modified client become the source of truth.

AstroZen instead sends raw, validated birth input to a server endpoint. The endpoint:

limits request size and rate;
resolves the place and time zone;
performs the Eastern and Western calculations;
returns a display model plus a detailed calculation context;
signs that context on the server.

raw birth input
  → place + IANA zone
  → UTC and declared solar-time strategy
  → deterministic chart engines
  → signed calculation context
  → optional interpretation

Checkout verifies the signature before accepting the context. A user can inspect the free result, but changing the browser payload does not silently change the evidence used for the paid report.

7. AI interprets evidence; it does not calculate the chart

The report-generation model receives the structured calculation context after the deterministic engines finish. It does not decide the coordinates, time zone, Four Pillars, planet positions, houses, or aspects.

That separation gives the system two useful properties:

Repeatability

The same supported input produces the same base chart. Generated prose may vary, but the underlying evidence does not.

Auditability

The report can show which calculated facts support an interpretation. When a factor is unavailable because the birth time is unknown, the model receives that limitation instead of a fabricated value.

This does not eliminate model errors. It constrains where they can occur and makes them easier to detect.

8. Tests should target boundaries, not just happy paths

The most valuable fixtures are not ordinary noon births in major cities. They are cases close to a boundary:

two cities with the same name in different countries;
dates around daylight-saving transitions;
births close to a solar-term boundary;
longitude corrections that cross midnight;
unknown-time inputs;
repeated identical inputs;
production builds that must load a WASM asset.

I also test invariants rather than only snapshots:

expect(unknownTime.pillars).toHaveLength(3);
expect(unknownTime.moon).toBeNull();
expect(unknownTime.ascendant).toBeNull();
expect(unknownTime.houses).toEqual([]);

An attractive result is not proof that the input pipeline is correct. Boundary tests are where hidden assumptions become visible.

What I would keep if I rebuilt it

The reusable lessons are not specific to birth charts:

Resolve human place names into structured, reviewable data.
Store an IANA zone, not a fixed offset.
Keep distinct time transformations separate and named.
Never turn “unknown” into a confident feature.
Make the server the source of truth for paid calculations.
Separate deterministic evidence from generative explanation.
Expose methodology choices and limitations in the product.

You can inspect the public explanation of the calculation pipeline on AstroZen’s methodology page, or try the free calculated chart. No email is required for the free calculation.

I would be especially interested in how other developers handle DST folds, historical time-zone data, and WASM assets in serverless deployments.

Scope note: BaZi and astrology are traditional symbolic systems used for reflection and entertainment. They are not scientifically validated diagnostic or predictive methods. Better engineering can make a calculation pipeline more consistent and transparent; it does not establish the scientific validity of the interpretation.