Knock Codes

→ Template

Modal Access Template

Gates one section of an already-visible page — content stays mounted and blurred behind a centered dialog instead of disappearing entirely.

Staging appAdvancedtemplatemodaloverlay

Best used for Gating one section of an already-public page without hiding the rest of it.

Wrap a single card, panel, or section instead of a whole route — the rest of the page stays visible and interactive, just not this one part.

Loading preview…
→ Hash your code

Generate a hash

Fully client-side — the plaintext code never leaves this page, and never touches a file. Only the hash below gets pasted into your project.

→ Installation

Add this template to your project

CLI

npx shadcn@latest add http://localhost:3000/r/react/modal-access-template.json

Running this site somewhere other than localhost? Set NEXT_PUBLIC_SITE_URL and this command switches to that host automatically.

Also installs

  • Knock Codes Core
  • Knock Codes Types
  • useKnockCodes
  • cx (classname helper)

Files created (8)

  • components/knock-codes/core/hash.ts
  • components/knock-codes/core/verify.ts
  • components/knock-codes/core/session.ts
  • components/knock-codes/core/storage.ts
  • components/knock-codes/react/types.ts
  • components/knock-codes/react/useKnockCodes.ts
  • components/knock-codes/react/cx.ts
  • components/knock-codes/react/ModalAccessTemplate.tsx

No CLI? Copy the files by hand

  1. Open the Code tab in the preview above.
  2. Create each path listed below in your project and paste its contents in.
  3. Do the same for anything listed under “Also installs”, if present.

Installing via an AI agent?

Drop AGENTS.md into your project root — it instructs any coding agent to hash the code locally, write only the hash, and confirm the plaintext never touched a file. Thin pointer files exist for tools that read a different filename.

AGENTS.mdCLAUDE.mdGEMINI.md.cursor/rules/knock-codes.mdc.github/copilot-instructions.md

→ Props

API reference

PropTypeDefaultDescription
expectedHashstring—SHA-256 hex hash to verify against, for local mode.
verifyVerifyFn—Custom async verification function, for server mode.
children *ReactNode—The gated section. Stays mounted, blurred, and inert while locked — rendered normally once unlocked.
logoReactNode—Rendered above the heading in the dialog — your own logo/wordmark. Omitted entirely if not passed.
supportHrefstring—Renders "Contact support" as a link to this URL.
onContactSupport() => void—Renders "Contact support" as a button instead of a link — e.g. to open a chat widget.
labelsModalAccessTemplateLabels—Overrides heading, description, input label, support label, and every KnockCodesLabels string.
fullPagebooleanfalseSet true if this template gates the entire page rather than one section, so the wrapper takes the full viewport height.
theme"light" | "dark"—Forces light or dark presentation on its own, independent of any ancestor ".dark" class. Omit to follow the nearest ".dark" ancestor if one happens to exist.
classNamestring—Extra classes on the outer wrapper.
→ Notes

Accessibility

The dialog carries role="dialog" and aria-modal="true"; the blurred content behind it is marked aria-hidden and inert while locked, so screen readers and keyboard focus skip it entirely. The code field autofocuses when the dialog opens. Errors and the submitting state announce through a shared aria-live="polite" region, same contract as every other block.

Customization

Everything is one file — backdrop, dialog, heading, description, field, button, and support link are all inline. Unlike the other templates, `children` renders even while locked (blurred and inert) instead of being swapped out, since the point is gating a section of a page that's otherwise visible. Pass `logo` and `labels` to customize; set `fullPage` if this is the whole page rather than one section of it.

→ Threat model

The honest version

Knock Codes stops casual visitors, search engines, and forwarded links. Local mode does not stop anyone who opens DevTools — the hash ships in your client bundle by design. Server mode (swap one prop) stops determined visitors. This is a velvet rope, with an optional real lock — never marketed as more than that.

→ Server mode

Need real protection?

Local mode is deterrence — the hash ships in your client bundle by design. Swap the expectedHash prop for a verify function pointing at one of these, and the code is checked server-side instead — same markup, same component, one prop different. Each template rate-limits attempts and returns a short-lived signed token on success.

nextjs-route-handler.js
// @ts-check
/**
 * Knock Codes — Next.js route handler server verification template.
 * Drop at app/api/verify-access/route.js (App Router).
 *
 * Set two env vars: KNOCK_CODES_SERVER_HASH, KNOCK_CODES_TOKEN_SECRET.
 *
 * Wire contract identical across all three server templates — see the
 * Cloudflare Worker template in this same folder for the full contract.
 */
import { createHash, createHmac } from "node:crypto";

const RATE_LIMIT_MAX_ATTEMPTS = 5; // adjust per deployment
const RATE_LIMIT_WINDOW_SECONDS = 60;
const TOKEN_TTL_MS = 5 * 60_000; // 5 minutes

// In-memory counter — acceptable ONLY for a single-instance/dev deployment.
// Vercel and most production hosts run multiple instances, so this counter
// would not be shared across them; swap in Redis or Vercel KV (a single
// shared store, same key scheme below) before deploying for real.
/** @type {Map<string, number>} */
const attemptsByKey = new Map();

/** @param {string} input */
function sha256Hex(input) {
  return createHash("sha256").update(input, "utf8").digest("hex");
}

/** @param {string} secret */
function signToken(secret) {
  const payload = Buffer.from(JSON.stringify({ exp: Date.now() + TOKEN_TTL_MS })).toString("base64url");
  const signature = createHmac("sha256", secret).update(payload).digest("base64url");
  return `${payload}.${signature}`;
}

/** @param {string} identifier */
function checkRateLimit(identifier) {
  const windowStart = Math.floor(Date.now() / 1000 / RATE_LIMIT_WINDOW_SECONDS);
  const key = `${identifier}:${windowStart}`;
  const attempts = attemptsByKey.get(key) ?? 0;
  if (attempts >= RATE_LIMIT_MAX_ATTEMPTS) return false;
  attemptsByKey.set(key, attempts + 1);
  return true;
}

/** @param {Request} request */
export async function POST(request) {
  const identifier = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || "unknown";
  if (!checkRateLimit(identifier)) {
    return Response.json({ ok: false, reason: "network" }, { status: 429 });
  }

  /** @type {unknown} */
  let code;
  try {
    ({ code } = /** @type {{ code?: unknown }} */ (await request.json()));
  } catch {
    code = undefined;
  }
  if (typeof code !== "string") {
    return Response.json({ ok: false, reason: "network" }, { status: 500 });
  }

  if (sha256Hex(code) !== process.env.KNOCK_CODES_SERVER_HASH) {
    return Response.json({ ok: false, reason: "invalid" });
  }

  return Response.json({ ok: true, token: signToken(/** @type {string} */ (process.env.KNOCK_CODES_TOKEN_SECRET)) });
}

→ Compose with

Blocks this template is built from

Drop down to these directly once you need more control than the single-file template gives you.