@grantry/nextjs 0.0.0-stage → 0.1.1

package/src/middleware.ts

@@ -0,0 +1,292 @@
+/**
+ * Route protection in Next.js middleware — `@grantry/nextjs/middleware`.
+ *
+ *   export default grantryMiddleware({
+ *     protectedRoutes: ['/dashboard', '/account'],
+ *     signInUrl: '/sign-in',
+ *   });
+ *
+ *   export const config = { matcher: ['/((?!_next|.*\\..*).*)'] };
+ *
+ * Middleware runs before rendering, so an unauthenticated visitor is redirected
+ * without the protected page ever being built — which is the difference between
+ * protecting a route and merely hiding it. No request is let through signed out,
+ * a support visit's included; see `visitTicket`.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import {
+  REDIRECT_URL_PARAMETER,
+  TICKET_PARAMETER,
+  environmentSignInUrl,
+  hostedSignInPage,
+  serverRouteOptions,
+  verifyToken,
+} from '@grantry/react/server';
+import { TOKEN_COOKIE_NAME, tokenFromCookie } from './cookie';
+
+/**
+ * The headers a verified request goes on with, for the application's pages to read.
+ *
+ * ⚠️ REMOVED FROM EVERY REQUEST THIS MIDDLEWARE SEES, NOT ONLY THE ONES IT VERIFIES. They were
+ * replaced on a protected route and passed through untouched everywhere else, so a visitor who sent
+ * `x-grantry-user-id: <anybody>` to a public page had it arrive as though this middleware had set
+ * it — and the docs tell a page it can trust these names. A page outside the middleware's `matcher`
+ * is still beyond reach, which is why `auth()`, which verifies the cookie itself, is the safer read.
+ */
+const FORWARDED_HEADERS = ['x-grantry-user-id', 'x-grantry-session-id'] as const;
+
+export interface GrantryMiddlewareOptions {
+  /**
+   * Path patterns requiring a signed-in visitor.
+   *
+   * A path prefix as a string — `'/dashboard'` protects it and everything under
+   * it — or a `RegExp` for anything else. `'/dashboard(.*)'`, the spelling other
+   * libraries use, means the same prefix; any other string that looks like a
+   * pattern is refused when the middleware is made (`prefixOf`).
+   * Anything not listed is public — an allowlist would silently protect new
+   * routes, which sounds safer but produces a site where adding a public page
+   * quietly breaks it.
+   */
+  protectedRoutes?: Array<string | RegExp>;
+  /**
+   * Where to send unauthenticated visitors.
+   *
+   * Unset: `GRANTRY_SIGN_IN_URL`, then `NEXT_PUBLIC_GRANTRY_SIGN_IN_URL` — the
+   * variable `<GrantryProvider>` reads, so the two agree — then the hosted
+   * sign-in screen on the environment's sign-in URL, which is looked up with the
+   * publishable key (one request, remembered for five minutes). With none of
+   * those the visitor is answered 401 (docs/paths-and-domains.md §6).
+   * ⚠️ It defaulted to `/sign-in`, a page Grantry could only guess the
+   * application had.
+   */
+  signInUrl?: string;
+  /** Override for self-hosted deployments and local development. */
+  apiUrl?: string;
+  /**
+   * Your publishable key, which names the application these tokens must belong
+   * to, and finds the hosted sign-in screen when no sign-in page is named. Read
+   * from `GRANTRY_PUBLISHABLE_KEY`, then `NEXT_PUBLIC_GRANTRY_PUBLISHABLE_KEY`,
+   * when omitted. ⚠️ With no key and no `environmentId`, a request carrying a
+   * token makes the middleware THROW (`no_audience`) rather than redirect — no
+   * token is ever admitted without knowing the application, and a sign-in page
+   * cannot fix a server that does not know which one it is. See
+   * `@grantry/react/server`.
+   */
+  publishableKey?: string;
+  /** The environment id, for a deployment that configures it directly. */
+  environmentId?: string;
+  /** Require a verified email address, not merely a session. */
+  requireVerifiedEmail?: boolean;
+}
+
+/**
+ * A string route pattern, as the path prefix it protects.
+ *
+ * ⚠️ `'/dashboard(.*)'` PROTECTED NOTHING UNTIL 1 OCTOBER 2026, AND THE DOCS SAID TO WRITE IT. A
+ * string was compared as a literal prefix, so the pattern matched only a path that began with the
+ * characters `/dashboard(.*)` — none — and the middleware let every request through, signed out.
+ * The quickstart, the middleware page and this file's own example all used it (the docs audit). It
+ * is the spelling Clerk's route matcher takes, so somebody arriving from there writes it too: it is
+ * read as the prefix it means, and anything else that looks like a pattern is refused rather than
+ * silently matched against nothing.
+ */
+export function prefixOf(pattern: string): string {
+  const prefix = pattern.endsWith('(.*)') ? pattern.slice(0, -'(.*)'.length) : pattern;
+  if (/[()*?+[\]{}|^$\\]/u.test(prefix)) {
+    throw new Error(
+      `Grantry: the route pattern "${pattern}" is not a path prefix. ` +
+        'Use a prefix such as "/dashboard", or pass a RegExp.'
+    );
+  }
+  const trimmed = prefix.replace(/\/+$/u, '');
+  return trimmed === '' ? '/' : trimmed;
+}
+
+function matchesPath(pathname: string, patterns: Array<string | RegExp>): boolean {
+  return patterns.some((pattern) => {
+    if (typeof pattern === 'string') {
+      // A prefix, anchored at a path boundary so `/dashboard` does not also
+      // protect `/dashboards-public`.
+      return pattern === '/' || pathname === pattern || pathname.startsWith(`${pattern}/`);
+    }
+    /*
+     * ⚠️ `lastIndex` RESET FIRST. A RegExp with the `g` or `y` flag remembers where its last match
+     * ended and starts the next `test` there, so `/^\/admin/g` matched one request, missed the
+     * next — letting it through signed out — and matched the one after.
+     */
+    pattern.lastIndex = 0;
+    return pattern.test(pathname);
+  });
+}
+
+/**
+ * Whether a path is protected, as written and as decoded.
+ *
+ * ⚠️ BOTH SPELLINGS, BECAUSE THE ROUTER AND THIS CHECK MAY NOT AGREE ON ONE. `nextUrl.pathname`
+ * keeps percent-encoding (`/%64ashboard`), and a router that decodes before it matches a page
+ * would build `/dashboard` for an address the prefix never saw. Matching the decoded path too
+ * costs nothing on an ordinary request and only ever protects more.
+ */
+function matches(pathname: string, patterns: Array<string | RegExp>): boolean {
+  if (matchesPath(pathname, patterns)) return true;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return false;
+  }
+  return decoded !== pathname && matchesPath(decoded, patterns);
+}
+
+/** The request as the application will see it, with no forwarded header the visitor wrote. */
+function withoutForwardedHeaders(request: NextRequest): Headers {
+  const headers = new Headers(request.headers);
+  for (const name of FORWARDED_HEADERS) headers.delete(name);
+  return headers;
+}
+
+/**
+ * A support visit's first request: a navigation carrying `?__grantry_ticket=`.
+ *
+ * ⚠️ CARRIED TO SIGN-IN, NEVER LET THROUGH. A view-as link opens the Home URL
+ * with its ticket (0242), and `@grantry/js` spends it on whatever page loads. A
+ * plain redirect to sign-in dropped the query string, so a protected Home URL
+ * turned every visit into a sign-in form for an operator with no password to
+ * type — and the first fix, letting the request through signed out, was a way
+ * past this middleware for anybody: the ticket is not checked here, so adding
+ * the parameter to any protected address rendered that page to a signed-out
+ * visitor. A page that trusted this middleware to keep its data from signed-out
+ * visitors would have served it.
+ *
+ * So the ticket rides the redirect instead. The sign-in page is public, the SDK
+ * spends the ticket there before anything else runs, and `<SignIn />` moves a
+ * visit on to `redirect_url` — the address the link pointed at, without the
+ * ticket. The protected page is only ever built for a signed-in request.
+ *
+ * Only GET and HEAD: a form post or a server action is never a navigation from a
+ * link, and carries nothing anywhere.
+ */
+function visitTicket(request: NextRequest): string | null {
+  if (request.method !== 'GET' && request.method !== 'HEAD') return null;
+  return request.nextUrl.searchParams.get(TICKET_PARAMETER) || null;
+}
+
+export function grantryMiddleware(options: GrantryMiddlewareOptions = {}) {
+  const {
+    protectedRoutes: patterns = [],
+    apiUrl,
+    publishableKey,
+    environmentId,
+    requireVerifiedEmail = false,
+  } = options;
+
+  // Read once, here, so a pattern that cannot work fails the deploy and not a visitor.
+  const protectedRoutes = patterns.map((pattern) =>
+    typeof pattern === 'string' ? prefixOf(pattern) : pattern
+  );
+
+  /**
+   * Where sign-in is: the option, the server's variables, the hosted sign-in screen.
+   *
+   * ⚠️ THE ONE SDK THAT DOES NOT DEFAULT TO REDIRECT SIGN-IN, because it cannot.
+   * A redirect sign-in keeps its verifier in the browser and spends its code
+   * there (docs/hosted-sign-in.md §6), and the only page this middleware knows
+   * is the protected one it is turning the visitor away from. Name a sign-in
+   * page — `<SignIn mode="redirect" />` makes one a single line.
+   */
+  async function signInPage(): Promise<string | null> {
+    const configured = options.signInUrl ?? serverRouteOptions().signInUrl;
+    if (configured) return configured;
+    const signInUrl = await environmentSignInUrl({
+      ...(publishableKey ? { publishableKey } : {}),
+      ...(apiUrl ? { apiUrl } : {}),
+    });
+    return hostedSignInPage(signInUrl, 'sign-in');
+  }
+
+  return async function middleware(request: NextRequest): Promise<NextResponse> {
+    if (!matches(request.nextUrl.pathname, protectedRoutes)) {
+      // A public page: through, with nothing that claims to be this middleware's word.
+      return FORWARDED_HEADERS.some((name) => request.headers.has(name))
+        ? NextResponse.next({ request: { headers: withoutForwardedHeaders(request) } })
+        : NextResponse.next();
+    }
+
+    const token = tokenFromCookie(request.cookies.get(TOKEN_COOKIE_NAME));
+
+    const turnAway = async (): Promise<NextResponse> => {
+      const signIn = await signInPage();
+      if (!signIn) {
+        return new NextResponse('Sign-in is required, and this application has no sign-in page.', {
+          status: 401,
+        });
+      }
+
+      const target = new URL(signIn, request.url);
+      const here = new URL(request.url);
+      // A support visit: the sign-in page spends the ticket, and the visit goes on to
+      // where the link pointed, without it. See `visitTicket`.
+      const ticket = visitTicket(request);
+      if (ticket) {
+        here.searchParams.delete(TICKET_PARAMETER);
+        target.searchParams.set(TICKET_PARAMETER, ticket);
+      }
+      /*
+       * So the app can return the visitor where they were headed rather than
+       * dumping them on a home page after signing in. ⚠️ A PATH WHEN SIGN-IN IS
+       * ON THIS ORIGIN, THE WHOLE ADDRESS WHEN IT IS NOT: on the hosted sign-in
+       * screen a path would name a page of the sign-in URL's. The query
+       * string goes too: `/dashboard?tab=billing` came back as `/dashboard`.
+       * The sign-in page follows it only on its own origin (`requestedRedirectUrl`).
+       */
+      target.searchParams.set(
+        REDIRECT_URL_PARAMETER,
+        target.origin === here.origin ? `${here.pathname}${here.search}` : here.href
+      );
+      const response = NextResponse.redirect(target);
+      // The ticket is in this address; the page it leads to has no need to be told where it came from.
+      if (ticket) response.headers.set('Referrer-Policy', 'no-referrer');
+      return response;
+    };
+
+    if (!token) return turnAway();
+
+    try {
+      const verified = await verifyToken(token, {
+        ...(apiUrl ? { apiUrl } : {}),
+        ...(publishableKey ? { publishableKey } : {}),
+        ...(environmentId ? { environmentId } : {}),
+      });
+
+      if (requireVerifiedEmail && !verified.emailVerified) {
+        return turnAway();
+      }
+
+      // Passed to the application so a server component can read the user
+      // without verifying a second time. Set on the *outgoing* request headers,
+      // which the visitor cannot forge — anything they send under these names
+      // is replaced here (and removed on public pages; see `FORWARDED_HEADERS`).
+      const headers = withoutForwardedHeaders(request);
+      headers.set('x-grantry-user-id', verified.userId);
+      headers.set('x-grantry-session-id', verified.sessionId);
+
+      return NextResponse.next({ request: { headers } });
+    } catch (cause) {
+      /*
+       * ⚠️ A MISSING AUDIENCE IS THE ONE FAILURE THAT MUST NOT REDIRECT. Every
+       * other reason means this request cannot be trusted, and the sign-in page
+       * is the honest answer; `no_audience` means the application never said
+       * which Grantry environment it belongs to, and sending the visitor to
+       * sign in would loop them forever against a check that can never pass.
+       */
+      if (
+        cause instanceof Error &&
+        cause.name === 'TokenVerificationError' &&
+        (cause as { reason?: string }).reason === 'no_audience'
+      ) {
+        throw cause;
+      }
+      return turnAway();
+    }
+  };
+}

package/src/provider.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+/**
+ * The React provider, saying "nextjs" — and reading `NEXT_PUBLIC_GRANTRY_*`.
+ *
+ * ## Why this file exists at all
+ *
+ * Everything else in this package is a straight re-export of `@grantry/react`,
+ * on the principle that a second implementation is a second thing to drift. So
+ * a wrapper needs a reason, and it has two:
+ *
+ * ⚠️ A NEXT.JS APP AND A PLAIN REACT APP ARE INDISTINGUISHABLE ON THE WIRE
+ * UNLESS ONE OF THEM SAYS SO. They render the same provider, construct the same
+ * client and send the same requests. That is normally a virtue and here it is a
+ * problem: the development Overview's setup guide watches for the merchant's
+ * app to connect and then shows them how to sign a user up *in the framework
+ * that connected*. Without this, everyone who installed `@grantry/nextjs` would
+ * be shown a plain-React snippet — no `middleware.ts`, no server helpers — on
+ * the one screen whose whole job is knowing what they are building.
+ *
+ * ⚠️ AND IT IS NOT DETECTABLE AT RUNTIME. `__NEXT_DATA__` exists only in the
+ * Pages Router, `process.env.NEXT_RUNTIME` is server-only, and sniffing for
+ * either would make the answer depend on which router the merchant chose. The
+ * honest signal is which package they installed, and this is the file that
+ * knows.
+ *
+ * ⚠️ THE SECOND REASON IS THE ENVIRONMENT VARIABLES, WHICH ONLY THIS PACKAGE
+ * CAN READ. Where the application's pages are is its own code since 0242 —
+ * `signInUrl`, `signUpUrl`, the fallback and force redirect URLs and
+ * `afterSignOutUrl`, Clerk's names — and a Next.js application sets them as
+ * `NEXT_PUBLIC_GRANTRY_*`. They become props of the React provider here, under
+ * whatever props were passed, so the rules stay `@grantry/react`'s.
+ */
+
+import {
+  GrantryProvider as ReactProvider,
+  mergeRouteOptions,
+  type GrantryProviderProps,
+  type RouteOptions,
+} from '@grantry/react';
+
+/**
+ * `NEXT_PUBLIC_GRANTRY_*`, as route options.
+ *
+ * ⚠️ EVERY NAME WRITTEN OUT IN FULL. Next.js puts a `NEXT_PUBLIC_` variable into
+ * the browser bundle only where `process.env.NAME` appears literally; a name
+ * built from a prefix is correct on the server and `undefined` in the browser,
+ * which is a hydration mismatch as well as a wrong link.
+ */
+function publicRouteOptions(): RouteOptions {
+  return {
+    signInUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_IN_URL,
+    signUpUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_UP_URL,
+    signInFallbackRedirectUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_IN_FALLBACK_REDIRECT_URL,
+    signUpFallbackRedirectUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_UP_FALLBACK_REDIRECT_URL,
+    signInForceRedirectUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_IN_FORCE_REDIRECT_URL,
+    signUpForceRedirectUrl: process.env.NEXT_PUBLIC_GRANTRY_SIGN_UP_FORCE_REDIRECT_URL,
+    afterSignOutUrl: process.env.NEXT_PUBLIC_GRANTRY_AFTER_SIGN_OUT_URL,
+  };
+}
+
+export function GrantryProvider(props: GrantryProviderProps) {
+  /*
+   * Props first, then the variables — Clerk's order — merged option by option,
+   * so a prop left undefined does not hide the variable beneath it.
+   *
+   * `props.sdk` after `sdk="nextjs"`, so it is genuinely a default rather than
+   * a lock. An application embedding this inside something else can still say
+   * what it is, and passing nothing — the normal case — reports `nextjs`.
+   */
+  const routes = mergeRouteOptions(props, publicRouteOptions());
+  return <ReactProvider sdk="nextjs" {...props} {...routes} />;
+}

package/src/server.ts

@@ -0,0 +1,159 @@
+/**
+ * Server-side auth for the Next.js App Router — `@grantry/nextjs/server`.
+ *
+ *   const { userId } = await auth();
+ *   if (!userId) redirect('/sign-in');
+ *
+ * Reads the access-token cookie the client SDK mirrors onto this app's domain
+ * and verifies it against Grantry's published keys. No network call in the hot
+ * path once the keys are cached, so this is cheap enough to use on every render.
+ *
+ * ⚠️ `auth()` IS THE APP ROUTER'S ALONE, SO THE VERIFIER IS EXPORTED BESIDE IT. It reads
+ * `next/headers`, which a Pages Router `getServerSideProps` or API route cannot call; those verify
+ * `req.cookies.grantry_token` with `verifyToken` themselves. The docs said "verify in
+ * getServerSideProps" while this entry point offered nothing to verify with, and a Next.js
+ * application is told not to install `@grantry/react` beside this package (the docs audit,
+ * 1 October 2026).
+ */
+import { cookies } from 'next/headers';
+import {
+  TokenVerificationError,
+  verifyToken,
+  type VerifiedToken,
+  type VerifyFailureReason,
+  type VerifyTokenOptions,
+} from '@grantry/react/server';
+import { TOKEN_COOKIE_NAME, tokenFromCookie } from './cookie';
+
+export interface AuthObject {
+  /** Null when the visitor is not signed in. */
+  userId: string | null;
+  sessionId: string | null;
+  environmentId: string | null;
+  emailVerified: boolean;
+  /**
+   * The operator, when this visitor is somebody from your team viewing as the user — the verified
+   * `act` claim. Refuse your own sensitive actions while it is set.
+   */
+  actor: { sub: string } | null;
+  /** The verified token, for callers that want the expiry or full claims. */
+  token: VerifiedToken | null;
+  /**
+   * Why authentication failed, when it did.
+   *
+   * `expired` in particular is worth distinguishing: it usually means the tab
+   * was asleep and the client will recover on its own, not that anything is
+   * misconfigured.
+   */
+  reason: TokenVerificationError['reason'] | null;
+}
+
+const SIGNED_OUT: AuthObject = {
+  userId: null,
+  sessionId: null,
+  environmentId: null,
+  emailVerified: false,
+  actor: null,
+  token: null,
+  reason: null,
+};
+
+export interface AuthOptions {
+  /** Override for self-hosted deployments and local development. */
+  apiUrl?: string;
+  /**
+   * Your publishable key — the same one the provider takes.
+   *
+   * ⚠️ IT IS WHAT SAYS WHICH APPLICATION A TOKEN MUST BELONG TO. Read from
+   * `GRANTRY_PUBLISHABLE_KEY`, then `NEXT_PUBLIC_GRANTRY_PUBLISHABLE_KEY` — the
+   * variable `<GrantryProvider>` is already given — when omitted, so the
+   * ordinary Next.js application passes nothing here. With no key and no
+   * `environmentId`, `auth()` throws `no_audience` rather than accepting a token
+   * minted for another application. See `@grantry/react/server`.
+   */
+  publishableKey?: string;
+  /** The environment id, for a deployment that configures it directly. */
+  environmentId?: string;
+}
+
+/**
+ * The current visitor, in a server component, route handler or server action.
+ *
+ * Never throws for an unauthenticated visitor — being signed out is an ordinary
+ * state, not an exception. The `reason` field carries the detail when a token
+ * was present but unusable.
+ */
+export async function auth(options: AuthOptions = {}): Promise<AuthObject> {
+  const store = await cookies();
+  const raw = tokenFromCookie(store.get(TOKEN_COOKIE_NAME));
+  if (!raw) return SIGNED_OUT;
+
+  try {
+    const token = await verifyToken(raw, options);
+    return {
+      userId: token.userId,
+      sessionId: token.sessionId,
+      environmentId: token.environmentId,
+      emailVerified: token.emailVerified,
+      actor: token.actor,
+      token,
+      reason: null,
+    };
+  } catch (cause) {
+    /*
+     * ⚠️ `no_audience` IS RETHROWN RATHER THAN REPORTED AS SIGNED OUT. It says
+     * this deployment never configured which application to accept tokens for,
+     * which is a fault in the app rather than a fact about the visitor —
+     * swallowing it would sign every user out at once and look like a broken
+     * cookie.
+     */
+    if (cause instanceof TokenVerificationError && cause.reason !== 'no_audience') {
+      return { ...SIGNED_OUT, reason: cause.reason };
+    }
+    throw cause;
+  }
+}
+
+/**
+ * `auth()`, but throws when nobody is signed in.
+ *
+ * For routes where being signed out is a bug rather than a case to handle —
+ * it narrows `userId` to a string, so the call site needs no null check and
+ * cannot forget one.
+ */
+export async function requireAuth(
+  options: AuthOptions = {}
+): Promise<AuthObject & { userId: string; sessionId: string }> {
+  const result = await auth(options);
+
+  if (!result.userId || !result.sessionId) {
+    throw new Error(
+      'requireAuth() was called but no user is signed in. ' +
+        'Use auth() and handle the signed-out case, or protect this route in middleware.'
+    );
+  }
+
+  return result as AuthObject & { userId: string; sessionId: string };
+}
+
+/*
+ * `verifyToken` for the Pages Router and anything else `auth()` cannot reach — see the note at the
+ * top. The same function `@grantry/react/server` exports, not a copy.
+ */
+export {
+  TokenVerificationError,
+  verifyToken,
+  type VerifiedToken,
+  type VerifyFailureReason,
+  type VerifyTokenOptions,
+};
+
+/*
+ * Spending a "Verify it's you" grant before a sensitive action (0330), with `auth()`'s `sessionId`
+ * and `userId` — the same function `@grantry/react/server` exports, for the reason above.
+ */
+export {
+  ReverificationCheckError,
+  verifyReverification,
+  type VerifiedReverification,
+} from '@grantry/react/server';