# Knock Codes

> Copy-paste "enter a code to continue" access screens. Single-file templates, zero runtime dependencies, MIT licensed. Template set version: 1.1.0.

## What this is
A shared-secret gate, not authentication. Everyone who has the code gets the same access — there is no per-user identity, no accounts, no permissions. Local mode hashes the code client-side (SHA-256) and compares in the browser; server mode swaps the `expectedHash` prop for a `verify` function so the comparison happens on a server instead. Neither mode invents rate limiting or an `attempts` prop on the client — rate limiting exists only in the reference server templates.

## Security model
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) hides the hash from the client; children you already bundled are still in the JavaScript, and a forged session works unless you wire validateSession. A velvet rope, with an optional real lock. Never marketed as more than that.

## Templates (content/templates/*.mdx, packages/react/*.tsx)

### Branded Access — branded-access-template (v1.1.0)
A copy-paste React password screen for client previews and private betas. One file, zero dependencies, local or server verification.
Detail page: /templates/branded-access
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check).
  - children: ReactNode — Rendered once unlocked.
  - logo?: ReactNode — Rendered on the brand panel (and, on mobile, above the form) — your own logo/wordmark.
  - tagline?: ReactNode — Short line under the logo on the brand panel. Hidden along with the rest of that panel below the lg breakpoint.
  - supportHref?: string — 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.
  - labels?: BrandedAccessTemplateLabels — Overrides heading, description, input label, support label, footer text, and every KnockCodesLabels string.
  - fullPage?: boolean (default: true) — Set false to embed this somewhere other than a real page root (a demo, a docs preview) — drops the full-viewport (100dvh) sizing.
  - 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.
  - remember?: "session" — Persists the unlocked session across reloads within the same tab via sessionStorage. Not a security boundary — see the security model.
  - className?: string — Extra classes on the outer grid.

### Knock Codes — knock-codes-template (v1.1.0)
A copy-paste React access screen for client previews and staging apps — segmented code entry, dark card, footer help text. One file, zero dependencies.
Detail page: /templates/knock-codes
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check).
  - children: ReactNode — Rendered once unlocked.
  - logo?: ReactNode — Rendered above the heading — your own logo/wordmark. Omitted entirely if not passed.
  - codeLength?: number (default: 8) — Total number of code boxes.
  - groupSize?: number (default: 4) — Boxes per group — a dash separates groups.
  - supportHref?: string — 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.
  - labels?: KnockCodesTemplateLabels — Overrides heading, description, access-code label, support label, footer text, and every KnockCodesLabels string.
  - fullPage?: boolean (default: true) — Set false to embed this somewhere other than a real page root (a demo, a docs preview) — drops the full-viewport (100dvh) sizing.
  - 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.
  - remember?: "session" — Persists the unlocked session across reloads within the same tab via sessionStorage. Not a security boundary — see the security model.
  - className?: string — Extra classes on the full-page backdrop.

### Minimal Access — minimal-access-template (v1.1.0)
A copy-paste React access screen for internal tools and quick gates — a single masked field, no frills. One file, zero dependencies.
Detail page: /templates/minimal-access
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check).
  - children: ReactNode — Rendered once unlocked.
  - logo?: ReactNode — Rendered above the heading — your own logo/wordmark. Omitted entirely if not passed.
  - supportHref?: string — 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.
  - labels?: MinimalAccessTemplateLabels — Overrides heading, description, input label, support label, footer text, and every KnockCodesLabels string.
  - fullPage?: boolean (default: true) — Set false to embed this somewhere other than a real page root (a demo, a docs preview) — drops the full-viewport (100dvh) sizing.
  - 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.
  - remember?: "session" — Persists the unlocked session across reloads within the same tab via sessionStorage. Not a security boundary — see the security model.
  - className?: string — Extra classes on the full-page backdrop.

### Modal Access — modal-access-template (v1.1.0)
A copy-paste React access screen for gating one section of a live page — a blur-overlay dialog, content stays mounted behind it. One file, zero dependencies.
Detail page: /templates/modal-access
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check).
  - children: ReactNode — The gated section. Stays mounted, blurred, and inert while locked — rendered normally once unlocked.
  - logo?: ReactNode — Rendered above the heading in the dialog — your own logo/wordmark. Omitted entirely if not passed.
  - supportHref?: string — 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.
  - labels?: ModalAccessTemplateLabels — Overrides heading, description, input label, support label, and every KnockCodesLabels string.
  - fullPage?: boolean (default: false) — Set 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.
  - remember?: "session" — Persists the unlocked session across reloads within the same tab via sessionStorage. Not a security boundary — see the security model.
  - className?: string — Extra classes on the outer wrapper.

### Plain HTML Gate — plain-html-gate (v1.0.0)
A copy-paste HTML password screen for static sites and legacy pages — no React, no build step, no npm install. One file, zero dependencies.
Detail page: /templates/plain-html-gate
Props:
  (no props beyond children)

## Blocks (content/blocks/*.mdx, packages/react/*.tsx)

### Access Denied Screen — access-denied-screen
A copy-paste React denial screen for a hard-locked route or a custom Protected Route fallback — no access-code form, no retry. Zero dependencies.
Detail page: /blocks/access-denied-screen
Props:
  - heading?: string (default: "Access denied") — The main heading.
  - message?: ReactNode (default: "You don’t have permission to view this page.") — Body copy under the heading.
  - action?: ReactNode — Optional call to action under the message.
  - variant?: "page" | "inline" (default: "page") — Outer positioning.

### Access Receipt — access-receipt
A copy-paste React session receipt for Knock Codes access screens — unlock time, storage mode, timeout. Zero dependencies.
Detail page: /blocks/access-receipt
Props:
  - storageMode?: "localStorage" | "sessionStorage" | "memory" (default: "localStorage") — Storage backend the active session used — shown on the Storage line.
  - timeout?: number (default: 1800000) — Session lifetime in milliseconds, formatted on the Timeout line.
  - verificationStrategy?: "local-hash" | "server-verify" (default: "local-hash") — Which verification strategy produced this session.
  - className?: string — Extra classes on the outer card.

### Embedded Gate — embedded-gate
A copy-paste React access screen for gating a widget or section inside an existing layout — Knock Codes, fixed to the inline shell. Zero dependencies.
Detail page: /blocks/embedded-gate
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - storage?: "localStorage" | "sessionStorage" | "memory" (default: "localStorage") — Where the unlocked session persists.
  - timeout?: number (default: 1800000) — Session lifetime in milliseconds.
  - children: ReactNode — Rendered once unlocked.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.

### Gate Wrapper — gate-wrapper
A copy-paste React layout primitive for composing a fully custom access-code UI — page-centered or inline positioning, no verification logic. Zero dependencies.
Detail page: /blocks/gate-wrapper
Props:
  - children: ReactNode — Content to position.
  - variant?: "page" | "inline" (default: "page") — "page" centers full-height (min-h-100dvh); "inline" flows naturally in place.
  - className?: string — Extra classes on the wrapper.

### Knock Codes — knock-codes
A copy-paste React access screen for gating a whole page or app root — local hash or server verification, one prop swap between them. Zero dependencies.
Detail page: /blocks/knock-codes
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode. Mutually exclusive with verify.
  - verify?: VerifyFn — Custom async verification function, for server mode. Mutually exclusive with expectedHash.
  - storage?: "localStorage" | "sessionStorage" | "memory" (default: "localStorage") — Where the unlocked session persists.
  - storageKey?: string (default: "knock-codes:session") — Storage key the session is written under.
  - timeout?: number (default: 1800000) — Session lifetime in milliseconds (30 minutes).
  - activityTracking?: boolean (default: false) — Sliding-timeout model — interaction rewrites expiry instead of a fixed TTL.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check). Omitted: expiry is the only restore check.
  - children: ReactNode — Rendered once unlocked.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.
  - variant?: "page" | "inline" (default: "page") — Outer positioning — full-page centered, or flows inline in an existing layout.
  - className?: string — Extra classes on the outer wrapper.

### Logout Button — logout-button
A copy-paste React logout control for Knock Codes access screens — clears the shared session on click. Zero dependencies.
Detail page: /blocks/logout-button
Props:
  - children?: ReactNode (default: "Log out") — Button label.
  - className?: string — Extra classes on the button.
  - onLoggedOut?: () => void — Called after the shared session is cleared.

### PIN Input — pin-input
A copy-paste React access-code field for building a custom gate on useKnockCodes — masked field or segmented boxes, paste support, accessible errors. Zero dependencies.
Detail page: /blocks/pin-input
Props:
  - value: string — Current input value (controlled).
  - onChange: (value: string) => void — Called on every keystroke/paste.
  - onSubmit: () => void — Called on Enter or the submit button, when not empty and not submitting.
  - submitting: boolean — Disables the field and shows the busy label.
  - error: KnockCodesError | null — Drives which error message renders in the status region.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.
  - autoFocus?: boolean — Focus the field (or first box) on mount.
  - variant?: "field" | "boxes" (default: "field") — Masked text field, or a segmented character grid.
  - length?: number (default: 6) — Slot count when variant is boxes.
  - groupSize?: number (default: 4) — Dash between groups when variant is boxes.

### Protected Card — protected-card
A copy-paste React access screen for gating one card in a dashboard grid — blurred preview, inline unlock. Zero dependencies.
Detail page: /blocks/protected-card
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - children: ReactNode — The card's content — blurred while locked, revealed once unlocked.
  - className?: string — Extra classes on the card.

### Protected Layout — protected-layout
A copy-paste React access screen for a Next.js layout or app root — header and footer stay visible while locked. Zero dependencies.
Detail page: /blocks/protected-layout
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - children: ReactNode — Rendered once unlocked.
  - header?: ReactNode — Rendered above the access-code prompt even while locked.
  - footer?: ReactNode — Rendered below the access-code prompt even while locked.

### Protected Modal — protected-modal
A copy-paste React access screen for a paywall-style preview — content stays mounted and blurred behind a modal prompt. Zero dependencies.
Detail page: /blocks/protected-modal
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - children: ReactNode — Stays mounted, blurred while locked.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.
  - className?: string — Extra classes on the outer relative container.

### Protected Route — protected-route
A copy-paste React access screen for route-level guarding — React Router or similar, with an optional custom denial state. Zero dependencies.
Detail page: /blocks/protected-route
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - children: ReactNode — Rendered once unlocked.
  - unauthorizedFallback?: ReactNode — Rendered instead of the default access-code prompt while locked. Omit for Knock Codes's default behavior.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.
  - variant?: "page" | "inline" (default: "page") — Outer positioning.

### Session Provider — session-provider
A copy-paste React session provider for Knock Codes access screens — shares one unlock state across a gate, a logout button, and a timeout banner. Zero dependencies.
Detail page: /blocks/session-provider
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - storage?: "localStorage" | "sessionStorage" | "memory" (default: "localStorage") — Where the unlocked session persists.
  - timeout?: number (default: 1800000) — Session lifetime in milliseconds.
  - validateSession?: (session: KnockCodesSession) => boolean | Promise<boolean> — Called when a session is read from storage. Return false or throw to reject it (server-mode token check).
  - children: ReactNode — Everything that should read the shared session via useKnockCodesContext().

### Session Timeout Banner — session-timeout-banner
A copy-paste React warning banner for Knock Codes access screens — alerts before a shared session expires, with a one-click logout. Zero dependencies.
Detail page: /blocks/session-timeout-banner
Props:
  - warnBeforeMs?: number (default: 60000) — Show the banner once this many ms remain before expiry.
  - className?: string — Extra classes on the banner.

### Standalone Gate — standalone-gate
A copy-paste React access screen for the fastest possible integration — wrap your app, pass a hash, done. Zero dependencies.
Detail page: /blocks/standalone-gate
Props:
  - expectedHash?: string — SHA-256 hex hash to verify against, for local mode.
  - verify?: VerifyFn — Custom async verification function, for server mode.
  - children: ReactNode — Rendered once unlocked.
  - heading?: string (default: "This page is protected") — Overrides just the heading — for everything else, use Knock Codes directly.
  - variant?: "page" | "inline" (default: "page") — Escape hatch for embedding a demo somewhere other than a real app root — a docs page, this gallery's own preview.
  - autoFocus?: boolean (default: true) — Focuses the code field on mount. Off in embedded previews so a newly-rendered gate can't steal focus and scroll the page.

### Unlock Dialog — unlock-dialog
A copy-paste React unlock dialog for triggering an access-code prompt from a custom button or menu item. Zero dependencies.
Detail page: /blocks/unlock-dialog
Props:
  - open: boolean — Whether the dialog is visible.
  - value: string — Current input value (controlled).
  - onChange: (value: string) => void — Called on every keystroke/paste.
  - onSubmit: () => void — Called on Enter or the submit button.
  - submitting: boolean — Disables the field and shows the busy label.
  - error: KnockCodesError | null — Drives which error message renders.
  - labels?: KnockCodesLabels — Overrides for every user-facing string.
  - footer?: ReactNode — Extra content under the form.

### Verification Loader — verification-loader
A copy-paste React loading indicator for a custom access-code form built on useKnockCodes. Zero dependencies.
Detail page: /blocks/verification-loader
Props:
  - label?: string (default: "Checking...") — Text next to the spinner.
  - className?: string — Extra classes on the container.

## Install
Copy a template file directly from its detail page, or:
  npx shadcn add @knock-codes/<registryName>
  npx shadcn add https://knock.codes/r/react/<registryName>.json
  npx shadcn add trivedi-vatsal/knock-codes/<registryName>

## Adapting a template with an AI agent
Each template detail page has an "Adapt with AI" button that copies a ready prompt for this exact purpose — it names the template's real props and explicitly asks the agent to preserve the expectedHash/verify verification logic rather than inventing new fields.

## Links
- Templates: /templates
- Blocks: /blocks
- Getting started: /getting-started
- Security model: /security
- Changelog: /changelog