Visitor Gates

The whole purpose of memo is to put gates between strangers and the hosted HTML. The gate flow is a tiny state machine. Every visitor request to /<slug>/* runs the same machine and either rejects or advances the visitor to the next step.

The state machine#

        ┌─── claims = readClaims(cookie, slug) ───┐
        │                                          │
        ▼                                          ▼
loadLink(slug) ──── not_found ───────────────► 404
        │
        ├──── inactive ──────────────────────► 403 "disabled"
        ├──── expired ───────────────────────► 410 "expired"
        ▼
     ok(link) ── nextStep(link, claims) ──────┐
                                              ▼
                          ┌── email ────►  /<slug>/email
                          ├── otp ──────►  /<slug>/otp
                          ├── password ─►  /<slug>/password
                          ├── nda ──────►  /<slug>/nda
                          └── view ─────►  /<slug>/   (canonical trailing slash)

nextStep is pure:

function nextStep(link, claims) {
  if (link.requireEmail        && !claims?.email)           return "email";
  if (link.verifyEmail         && !claims?.email_verified)  return "otp";
  if (link.passwordHash        && !claims?.password_passed) return "password";
  if (link.requireAgreementId  && !claims?.nda_signed)      return "nda";
  return "view";
}

Every gate page calls loadLink + readClaims + nextStep. If the next step isn't the page you're on, you get redirected. This makes the gates idempotent — refreshing or deep-linking always lands you on the right gate.

Cookies + JWT#

The cookie name is memo_v_<slug> (lowercased, alphanumerics + -_ only). Attributes:

• HttpOnly — never readable from JS.
• Secure — set automatically when the request scheme is https:.
• SameSite=Lax — keeps the cookie out of cross-site forms but allows top-level navigation.
• Max-Age=86400 — visitors must re-enter the gate flow daily.

The cookie value is a jose HS256 JWT issued by src/lib/auth/visitor-jwt.ts. Payload:

type VisitorClaims = {
  sub: string;             // UUID, also reused as visits.id
  slug: string;            // bound to this slug
  email?: string;
  email_verified?: boolean;
  password_passed?: boolean;
  nda_signed?: boolean;
  signature_id?: string;
};

The signing key is daily-rotated:

• memo:jwt:key:current — written by the rotate-jwt-key cron.
• memo:jwt:key:previous — kept for 48 h grace, so visitors with a stale cookie never see a hard logout the moment the cron fires.
• MEMO_JWT_KEY_FALLBACK — env var, used until the first rotation succeeds.

verifyVisitorJwt tries the current key, then the previous, and returns null if neither works.

Per-gate behavior#

Email#

/<slug>/email is a single <input type=email>. The POST handler at /api/v/<slug>/email:

1. Ratelimits at 10/min/(slug, IP) via Upstash.
2. Zod-validates and lower-cases the email.
3. Calls emailAllowedByLink(link, email) — block-list wins; if no allowlist is set, anything not blocked passes.
4. If link.verifyEmail, issues a 6-digit OTP via issueOtp (Redis SET ... EX 300 NX) and sends through Resend.
5. Re-signs the JWT with email set (and email_verified: !link.verifyEmail).
6. Returns 303 to nextStep(link, claims).

OTP#

/<slug>/otp shows the masked email. POST handler:

1. Ratelimits at 10/min/(slug, IP).
2. Reads the claims cookie. If claims.email is missing the visitor is bounced back to /<slug>/email.
3. Validates the 6-digit code via verifyOtp — atomically deletes on match so codes aren't reusable.
4. Re-signs JWT with email_verified: true.

Password#

POST handler at /api/v/<slug>/password:

1. Ratelimits at 10/min/(slug, IP).
2. Calls verifyPassword(plain, { hash, salt }) — argon2id with the env pepper.
3. Re-signs JWT with password_passed: true.

NDA#

/<slug>/nda renders the agreement body (set:html from Tiptap output) with a "type your full name" input. POST handler at /api/v/<slug>/sign:

1. Ratelimits at 5/min/(slug, IP).
2. Reads claims, asserts claims.email exists (NDAs without identifying the signer are worthless).
3. Inserts a signatures row with the typed-name SVG, agreement_version_hash (frozen at sign time so re-edits of the agreement don't invalidate prior signatures), IP, UA.
4. Audit-logs action=nda.sign.
5. Publishes a QStash job to /api/cron/render-signed-pdf with the signature_id. The PDF is rendered asynchronously by lib/pdf/generate.ts (lazy @sparticuz/chromium-min + playwright-core) and back-fills signed_pdf_r2_key.
6. Re-signs JWT with nda_signed: true, signature_id.

View#

/<slug>/ is the destination — the canonical trailing-slash URL identical to what the owner shared. (/<slug>/view is a permanent 308 redirect to here, kept for any pre-existing bookmarks.) Why the trailing slash matters: served HTML often has refs like <img src="hero.png">, which the browser resolves against the document's directory. /<slug> (no slash) makes the browser treat <slug> as a file and resolves to /hero.png (root 404). /<slug>/ resolves to /<slug>/hero.png and hits the asset catch-all correctly. The index.astro handler 308-redirects /<slug> → /<slug>/ once gates pass.

The handler then:

1. One last nextStep check.
2. Insert (or no-op) a visits row keyed by claims.sub.
3. Look up the entry file: index.html in the version, else the first text/html file.
4. Stream the bytes from R2, decode to UTF-8.
5. Inject the visitor chrome (watermark SVG, beacon, recording snippets, optional print/contextmenu disable).
6. Return as text/html; charset=utf-8 with Cache-Control: private, no-store.

Per-asset requests (images, JS, fonts) go through /<slug>/raw/<path> which re-runs the gate check before streaming the asset. There is no public CDN cache — visitor content is private.

Rate limit summary#

All limiters are sliding-window via @upstash/ratelimit.

Shared gate factories#

The link gate and the space gate are the same state machine over two entities. The per-step POST handlers are produced by factories in src/lib/visitor/gate-handler-factories.ts:

createEmailHandler(opts) · createOtpHandler(opts) · createPasswordHandler(opts) · createSignHandler(opts)

Each factory takes a GateHandlerOptions describing how to load the entity, read/sign the JWT, compute the next step, and build the cookie — so /api/v/<slug>/email and /api/s/<spaceSlug>/email share one implementation. Links pass the link loaders; spaces pass loadSpace / readSpaceClaims / signSpaceVisitorJwt / the memo_vs_ cookie builder. The generic cookie/step helpers (nextStepFor, cookieNameFor, readClaimsFromCookie, cookieHeaderFor, …) live in gate.ts and are wrapped by both gate.ts (links) and space-gate.ts (spaces).

A non-ok load maps to the right status via a shared helper: inactive → 403, expired → 410, else 404 (the internal status string is no longer leaked as the body). The email factory also runs an optional checkTeamAccess hook — see Teams.

Space gates#

A space gate is the link gate over a spaces row. loadSpace / spaceNextStep / readSpaceClaims mirror the link helpers; the POST routes at /api/s/<spaceSlug>/{email,otp,password,sign} are the shared factories above. Once spaceNextStep === "view", content is served by the native viewer (/s/<slug>/p/<projectId>/), never by redirecting to a link. Full detail: Spaces → The gate.

NDA signing#

The sign handler writes a signatures row. Because signatures.link_id FKs to links, a space signature must write space_id instead — the factory's signatureTarget: "linkId" | "spaceId" option routes the entity id to the correct column (links default to linkId; the space sign route sets signatureTarget: "spaceId"). Writing a space id into link_id would raise a FK violation, so this routing is load-bearing.

Slug binding#

readClaims(cookie, slug) (links) and readSpaceClaims(cookie, slug) (spaces) reject a token whose slug claim doesn't match the requested slug — a JWT minted for A is never honored for B even if its cookie reaches B's handler. Cookie naming (memo_v_<slug> / memo_vs_<spaceSlug>) already isolates by slug; the claim check is defense-in-depth.

Chrome injection#

After view, injectVisitorChrome(html, opts) (src/lib/visitor/watermark.ts) appends, before </body>: the watermark SVG overlay (when watermark), screenshot-protection CSS, memo-visit / memo-slug / optional memo-scope metas, the beacon (beacon !== false), the Q&A widget (qaWidget !== false), download/contextmenu disable (unless allowDownloads), and branding CSS vars. The space viewer passes scope: "space", qaWidget: false, and beacon only when there's a session; extraTail carries the recording snippet.

What this design buys us#

• No third-party in the critical path. Even Clerk isn't reachable from visitor pages. If Clerk goes down, owners can't sign in but visitors keep working.
• Cookie lifecycle is bounded. 24h max age + daily key rotation + 48h previous-key grace means stolen cookies decay quickly.
• State machine is render-proof. A visitor can refresh, deep-link, or be sent the wrong URL and the machine still lands them on the right step.
• Audit trail is complete. Every gate pass writes to audit_logs indirectly via the JWT mutation; every NDA sign writes an explicit row.