Maintain Privacy Gates in Three Modes
One gate, three doors: a shared passcode, a verified email on the firm's list, or a link minted for one person. Each opens only what it names.
- Path
- blueprints/Maintain-Privacy-Gates-in-Three-Modes.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5 (1M context)
- Tags
- Blueprint · Confidential-Access · Privacy-Gates · Authentication · Signed-Link-Tokens · Email-Verification · Roster-Providers · SSR-Gating · Investment-Memos · Cross-Site-Pattern
Maintain Privacy Gates in Three Modes
Why Care?
Venture firms want to show more than they can publish. A portfolio page is public; the investment memo behind each company is not. A deck is for the people in the room; the deck’s appendix is for the people who wired money. Every site in this family has met that problem, and every site solved it again, a little differently, with its own cookie, its own passcode hashing, and its own holes.
This blueprint is the map those solutions add up to. A visitor gets through a gate by one of three doors:
- A shared secret. One passcode, handed out by hand. Cheap, deniable, and anonymous: you know a holder got in, not who.
- A verified email on the firm’s list. The visitor proves they own an address, and the address (or its domain) is on a roster: a firm’s LP list, a client’s staff, a co-investor’s partners.
- A link minted for one person. The link is the credential. It names who it was for, what it opens, and when it stops working.
Behind all three sits the same rule: a session says what it opens, and a page checks that it names the page. The rest of this document is how to keep that true.
Lineage
Three generations are live in the tree. This blueprint keeps what each got right.
| Generation | Where | What it got right | Where it went wrong |
|---|---|---|---|
| v1: passcode + plain cookie | hypernova-site, dark-matter | Request-time memo fetch from a private repo ([[GitHub-Secure-Content-Pattern]]); email capture | Middleware trusts any non-empty cookie; email mode never checks the visitor owns the address |
| v2: server sessions + signed links + telemetry | calmstorm-decks, chroma-decks, eventcut-ai | Per-recipient HMAC links with use limits and revocation; bot-safe link previews; who-saw-what telemetry | Needs a database; fails open when the database is down |
| v3: stateless signed cookie | mpstaton-site /promote, client-portals-site |
No store; HMAC payload; constant-time compares; path-scoped cookies; fail closed | mpstaton never checks the cookie’s scope; a dev bypass that works in production |
Docs this reconciles: [[Confidential-Content-Access-Control-Blueprint]] (v1), [[Maintain-Confidential-Access-with-Persistent-Sessions-and-Auth-Telemetry]] (v2), [[Build-a-Promotion-Surface-for-Investment-Opportunities]] (the hard gate), and the “Privacy and gating” section of [[Build-a-Client-Portals-Site]]. Their tier numbers conflict (v1’s Tier 1 is the passcode; v2’s Tier 1 is the signed link). This document drops tier numbers and names modes instead, so the order implies nothing about strength.
Calibrate first: courtesy or contract?
Not every gate needs all three doors. Decide which you are building before writing code; [[Security-Overkill-for-Avoiding-Brand-Rank]] and the “Polite Gate Posture” in [[Build-a-Fundraise-Deck-Workspace]] are the calibration docs.
- Courtesy. The threat is being findable: crawlers, AI indexers, a curious
click.
noindex,X-Robots-Tag, no sitemap entry, codenames. No gate at all. - Passcode. The threat is casual onward sharing of a URL. Mode 1.
- Named access. The content is confidential to a known set of people (LPs, a client’s team), and you need to know who saw it. Modes 2 and 3.
The investment memo case is named access. Memos carry deal terms, valuations, and diligence findings about companies that did not consent to publication.
The model
Scopes
A scope is the unit a gate protects. It is a string the content declares, not a URL prefix:
memo:cognitive-scientific one company's memo
memo:* every memo
portal:9peyu4 one client portal
Content declares its scope in its own frontmatter or config (gate.scope). Rosters,
passcodes, and links grant scopes. A page renders gated content only when the
session’s scopes match the content’s scope (memo:* matches memo:anything).
The session payload
One cookie shape for every mode, signed, never stored:
interface GateSession {
sub: string; // who: an email, a link's recipient label, or "passcode"
via: 'passcode' | 'email' | 'link';
scopes: string[]; // what it opens; checked on every gated render
exp: number; // unix seconds
jti?: string; // link id, for revocation and attribution
who?: { name: string; email: string }; // self-reported, passcode sessions only (see below)
}
// cookie value: base64url(JSON(payload)) + "." + HMAC-SHA256(payload, GATE_SESSION_SECRET)
This is the client-portals gate.ts kernel with the payload widened from one
portal id to sub + via + scopes. Everything else in that file carries over:
timingSafeEqual, HttpOnly; SameSite=Lax; Secure, safeNext() against open
redirects, the export token for headless PDF rendering.
Scopes are re-derived, not just trusted, for mode 2. An email session’s scopes are computed from the roster when the session is minted; when the roster changes (an LP’s access is removed), the next re-check should drop them. Keep email sessions short (7 days) and re-resolve the roster on mint. Passcode and link sessions carry their scopes for their lifetime.
Mode 1: shared passcode
- One env var per passcode, holding the plaintext or a scrypt hash with a
per-deployment salt (
GATE_PASSCODE_<NAME>). A config file maps passcode names to scopes. - Compare with
timingSafeEqualaftertrim(). Case-sensitive unless the config says otherwise. sub: "passcode",via: "passcode". Anonymous by design. If attribution matters, calmstorm’s-<label>suffix trick (the visitor typescode-acme) setssubto the label without a second secret.
Mode 2: verified email against a roster
Two halves, and both are required. dark-matter shipped only the second half, which means anyone who types a listed address gets in.
Prove ownership. Pick one:
- Email one-time code (recommended for LP audiences). The visitor enters an
address; the server sends a six-digit code and sets a short-lived signed
challenge cookie
{email, codeHash, exp: 10 min}; the visitor types the code. Stateless, works with any mailbox, no OAuth app per site. Needs a transactional email sender (Resend) on a domain with SPF and DKIM. - Google or Microsoft sign-in. Better UX when the whole roster is on Google Workspace or Microsoft 365, which LP rosters rarely are (family offices, personal addresses). Pattern: fullstack-vc’s OAuth callbacks.
- The shared identity service (
id.didi.sh), once it federates to sites outside.didi.sh. It already does magic links over Resend.
Check the roster. Look up the verified email in the roster and mint a session with the scopes it grants. No match: say so plainly, log the attempt, and offer a “request access” path. Do not fall through to the passcode form silently; the fullstack-vc post-mortem (UX failed on silent bounces) is the reason.
Mode 3: per-recipient link
- A link token is a signed payload
{jti, sub, scopes, exp, max_uses?}, minted by a CLI or an admin page and sent by a human. Redeeming it sets the session cookie and redirects to the content. - Bot-safe previews (from calmstorm): if the user agent is a link unfurler, serve OG tags only and do not redeem.
- Revocation without a database: a
GATE_REVOKED_LINKSenv list ofjtis, checked on redeem and on every gated render. RotateGATE_SESSION_SECRETto revoke everything. - Use limits need state. If
max_usesor a per-link audit trail matters, add the v2 store (Astro DB + Turso:MintedToken,Session,AuthEvent). Fail closed when that store is down; this is the one v2 behavior not to copy.
Naming the passcode reader (a layer on mode 1)
A shared passcode is the door people actually use: it works on the first try, from any device, with nothing to set up. It is also anonymous, and for named-access content (the investment memo case) “someone with the passcode read the Chroma memo” is not good enough. Mode 2 fixes that properly but needs a sending domain and a roster; until then, and for the readers who will always prefer the passcode, ask.
This is not a fourth door. It grants nothing, checks nothing, and changes no scope. It attaches a self-reported name to a passcode session and tells the firm.
What the visitor sees
- The modal, once, right after a passcode unlock. Title “Who’s reading?”, two
fields (name, email), one sentence on where it goes (“Your name and email go to
Humain Ventures and nowhere else”), and two buttons: Continue and Not now.
A native
<dialog>; Escape means Not now. - The popover, after “Not now”. A small card in the bottom-right corner, same
two fields, on every page view of the gated area. Its job is to be mildly
annoying, never in the way:
- no backdrop, no focus trap, never over the reading column;
- a close button that hides it for the current page only;
- after three closes it collapses to a slim bar (“Tell us who’s reading”) that stays until submitted.
- Nothing, once submitted. The server re-mints the session with
whoset, so the prompt stops on that browser for the life of the session.
Sessions from mode 2 or 3 already know who they are and never see it. Both pieces are
one Svelte island (IdentifyPrompt.svelte) mounted by the gated layout when
session.via === 'passcode' && !session.who. The snooze count lives in a plain
cookie; it is UX state, not security state.
Calibrate it like the gate. ask (above) suits a courtesy-to-named spectrum;
require makes the modal non-dismissible for content where an anonymous read is
unacceptable. At require, consider whether you actually want mode 2.
The endpoint
POST /api/<area>/identify with name, email, and a hidden honeypot field.
- Requires a valid passcode session; otherwise 401. It can’t be used to probe the roster, because it never reads one.
- Trims and caps lengths (name ≤ 120, email ≤ 254), checks email shape, rejects a filled honeypot silently.
- Re-signs the session with
who: { name, email }and the samescopes/exp. - Hands a record to the configured sink, after responding (Vercel
waitUntil), with a short timeout. The visitor’s reading never waits on, or fails because of, the sink. Sink failures are logged (rule 8 below).
interface Identification {
name: string;
email: string; // self-reported, NOT verified; label it so downstream
via: 'passcode';
passcode: string; // which passcode name, e.g. "lp"; never its value
scopes: string[];
firstPath: string; // the page they were on when they answered
at: string; // ISO timestamp
}
interface IdentifySink { send(r: Identification): Promise<void> }
Where the name goes: sinks
| Sink | Holds a back-office token? | When |
|---|---|---|
log |
No | Default; the record lands in the function log / log drain. |
slack |
No (a webhook URL) | The partners want a ping in a channel. |
queue |
No | Append to a private store (Upstash/Vercel KV, a Blob, a private-repo file); drained into the CRM later. |
decile |
Yes | Real-time write into Decile Hub from the server function. |
The queue sink keeps the Sync, don’t call
rule intact: the back-office token stays wherever the drain runs. The decile sink
bends it, deliberately and narrowly: one write per identification, never per page,
after the response. Choose it only when the partners want the CRM updated as it
happens, and give the site its own low-privilege Decile token (a user token, not an
admin one; GET /api/v1/whoami shows which you have), not the token the roster
sync uses.
Routing into Decile Hub
The same three steps whether a script drains the queue, the server function writes
directly, or an agent works the queue through the Decile MCP. Per the
decile-hub-connector skill (raw Authorization token, tenant subdomain,
/api/v1/):
| Step | REST | Decile MCP tool |
|---|---|---|
| 1. Is this email already a person? | GET /api/v1/people?email=<email> |
search_people_orgs (q = the email) |
| 2a. Known person: record the visit | POST /api/v1/people/{id}/notes { note: { body, context } } |
add_person_note (person_id, body, context) |
| 2b. New person: create, tagged | POST /api/v1/person (upsert by email) with first_name, last_name, email, tag_list, note |
create_or_update_person |
| 3. Optional: ask a partner to follow up | POST /api/v1/tasks (title, assignee_id; needs the account’s hub_tasks flag) |
create_task (subject_type: Person, subject_id, action_type: follow_up) |
- Never upsert over a known person.
POST /api/v1/personmatches by email and overwrites the fields you send, so a visitor typing “Bob” would rename the LP record “Robert Smith”. For a match, only add the note (2a). - Say it’s self-reported. Note body:
Investor area: opened with the shared passcode ("lp") and gave this name and email (self-reported, not verified). First page: /lp/memos/chroma/. 2026-10-14 15:02 UTC.Context:Investor portal. - Tag new people (
Investor-Portal-Visitor) so the partners can filter them, and split the typed name on the last space forfirst_name/last_name. - The MCP is for agents, not the site. A website can’t call an MCP server; it is how Claude Desktop or Claude Code acts on the queue (“file the new portal visitors into Decile”). The site’s direct path is the REST API.
Triage against the LP list, and a link back
Two cheap additions that make the answer useful without verifying it (humain-web, 2026-10-14):
- Match against the roster on submit. A plain, hand-editable
LP_ROSTERenv var (email, Labellines or JSON, generated bysync-roster --plain) plus the hashedGATE_ROSTER. The label (“Fund I LP”) is saved with the answer, set on the analytics profile and written into the CRM note. Never tell the visitor, or the form becomes a way to test whether an address is an LP. It is triage, not identity: anyone can type an LP’s email. - Email a personal link back. Mint a mode-3 link with the session’s own scopes
(30 days) and send it to the address given; the thanks message names the sender
to look for. It costs no confirmation step, rewards an honest answer with a
passcode-free bookmark, and turns later visits into named link sessions. A wrong
address only sends the link to whoever owns it, with no more access than the
passcode already gave. Any verified Resend domain works as the sender; humain-web
uses didi.sh’s (
no-reply@didi.sh) until humain.vc is set up.
For humain-web
- Turn it on as
askfor thelppasscode. - Sink:
queue, drained bypnpm sync-visitors(next tosync-roster, same~/.secretstoken, never on Vercel) or by an agent with the Humain Decile MCP. Move todecileonly if the partners decide real-time matters more than keeping the Decile token off the site, which today is a stated rule. - An email address that matches the roster can later be offered the email door instead, once it is switched on.
Rosters: where the list comes from
Mode 2 needs a list of people and the scopes each may open. Treat the source as a plug-in behind one interface, so the gate never knows whether the list came from a YAML file or a fund back-office:
interface RosterEntry {
email: string; // lower-cased, exact
scopes: string[];
label?: string; // "Fund I LP", "SPV LP", "GP"
source: string; // "yaml" | "decile" | "twenty" | ...
}
interface RosterProvider { load(): Promise<RosterEntry[]> }
| Provider | When | Notes |
|---|---|---|
| YAML in a private repo | Small, hand-kept lists | The default. Same private-repo read as the content. |
| Domain rule | “Anyone at @firm.com” | A roster entry with domain: instead of email:. Never for consumer domains (gmail.com, outlook.com). |
| CRM (Twenty) | Client staff, co-investors | Query people by organization or tag. |
| Fund back-office (Decile Hub) | A firm’s LPs | See below. |
Sync, don’t call. A roster provider runs on a schedule (a script, a GitHub
Action, or a Vercel cron), writes a normalized roster.json to a private store,
and the site reads that file at request time with a short cache. The site never
calls the back-office on a visitor’s request: back-office APIs are slow, unmetered,
and hold far more than the gate needs. The back-office token lives only where the
sync runs.
Decile Hub as a roster provider
Decile Hub has no “is this email an LP” call. The authoritative path, per the
decile-hub-connector skill:
GET /api/v1/entitiesto find the fund and SPV entities.GET /api/v1/entities/{entity_id}/capital_accountsfor each. This lists accounts by name andpartner_type(limited_partner/general_partner), with no emails.GET /api/v1/capital_accounts/{id}for each account, which carriesprimary_contact.emailandcontacts[].email.- Map entity to scopes in config (a fund entity grants
memo:*; an SPV entity grants the one company it invested in), union per email, writeroster.json.
Auth is Authorization: <raw token> (no Bearer), against the firm’s tenant
subdomain. One call per capital account, so this belongs in the sync, never in a
request. Pipeline prospects are not LPs; don’t build the roster from investor
pipelines unless the gate is meant for prospects.
Keeping gated content out of the build
A gate in front of a static file is a sign on an unlocked door. Gated content must
not be in dist/, the client bundle, the public repo, or a CDN cache.
- Gated routes are server-rendered (
export const prerender = false) on an adapter (@astrojs/vercel). Public pages stay prerendered. - Content lives in a private repo and is read at request time with a fine-grained token ([[GitHub-Secure-Content-Pattern]]; client-portals-site’s live collections). The site’s own repo holds only the public layer.
- Locked responses never include the content, not even hidden. Render the
unlock form in its place (
context.rewriteto the unlock page keeps the URL). - Caching: gated responses send
Cache-Control: private, no-storeandVary: Cookie; on Astro 7’s route cache,Astro.cache.set(false). - Search: don’t put gated text in a public Pagefind index ([[Nuances-of-Search-and-Privacy-Courtesy]]).
- Sanitize on publish, not on render. Content generated by tools (memos from memopop, for instance) carries local file paths, internal notes, and broken image paths. A publish step rewrites it into a clean, reviewable folder; the site renders only that folder.
How to follow it
- Calibrate. Courtesy, passcode, or named access? Write it in the site’s plan.
- Declare scopes on content.
gate: { scope: memo:<slug> }in frontmatter. - Start from client-portals
gate.ts, widen the payload toGateSession, add ascopeMatches(session, scope)and use it on every gated render. - Add modes as needed: passcode first; then email OTP + roster; then links.
- Middleware decides only “is this path gated, and does the cookie verify?” The page decides “does the session’s scope cover this content?” Both run.
- Fail closed everywhere: missing secret, missing roster, store down.
- Dev bypass only behind
import.meta.env.DEV. - Log every attempt (mode, outcome,
sub, scope, reason) somewhere you can read: an AuthEvent table, OpenPanel events, or a log drain. Silent failures are how gates die in practice ([[Delivering-A-Deck-To-A-Client-Who-Will-Not-Log-In]]). What readers do after the gate (time on page, scroll depth, downloads) is [[Maintain-Base-Engagement-Analytics]]; gated reading data stays first-party. - Test the kernel (client-portals’
tests/gate.test.tsis the starting suite) and drive the locked and unlocked paths in a browser before handing over.
Environment variables
| Var | Mode | Purpose |
|---|---|---|
GATE_SESSION_SECRET |
all | HMAC key for sessions, links, and email challenges (32+ random bytes) |
GATE_PASSCODE_<NAME> |
1 | A passcode (plaintext or scrypt hash) |
GATE_ROSTER_URL or repo path |
2 | Where roster.json lives |
RESEND_API_KEY, GATE_EMAIL_FROM |
2 | One-time code delivery |
GATE_REVOKED_LINKS |
3 | Comma-separated revoked jtis |
GATE_EXPORT_TOKEN |
all | Lets headless Chrome render a gated print route |
GATE_DEV_BYPASS |
dev | Honored only when import.meta.env.DEV |
GATE_IDENTIFY |
1 | off (default), ask, or require: the name-the-reader layer |
GATE_IDENTIFY_SINK |
1 | log (default), slack, queue, or decile |
GATE_IDENTIFY_SLACK_WEBHOOK |
1 | For the slack sink |
DECILE_API_URL, DECILE_HUB_API_KEY |
1 | Only for the decile sink; a dedicated low-privilege token |
GITHUB_CONTENT_TOKEN |
content | Read-only token for the private content repo |
Existing sites use other prefixes (PORTAL_, PROMOTE_, UNIVERSAL_PORTFOLIO_).
Don’t rename them as a side effect; adopt GATE_ in new sites.
Anti-patterns
- Trusting a cookie because it exists. Verify the signature and the scope.
- An email box with no ownership check. That’s a guestbook, not a gate.
- One session that opens everything when the content has scopes.
- Calling the back-office per request, or shipping its token to the browser.
- A gated page that is also prerendered, or a memo in
src/content/of a public repo. - Failing open when a database, secret, or roster is missing.
- Inventing a fourth door before the three here are exhausted. (Naming the passcode reader is a layer, not a door: it grants nothing.)
- Treating a self-reported name as identity: using
whofor scopes, overwriting CRM records with it, or calling it verified. - Making the reader wait on the CRM. Sinks run after the response.
Open questions
- Extract the kernel as a shared package? Three proposals exist
(
@knots/auth-patterns,@lossless-group/access,lossless-auth-core) and no site has adopted one. Wait for the second site on this blueprint. - Should mode 2 federate to
id.didi.shinstead of each site sending its own codes? - Naming the reader: does a submitted email that matches the roster upgrade the session (no), or prompt the reader to use the email door (probably, once it’s on)?
- Env naming drift: humain-web’s scripts read
DECILEHUB_API_KEY; thedecile-hub-connectorskill standardizesDECILE_HUB_API_KEY.
Related
- [[Maintain-Base-Engagement-Analytics]]: what readers do once inside, attributed to the identity this gate establishes (including the name-the-reader layer)
- Once this blueprint is signed off, the v1 and v2 blueprints get
superseded_by: [[Maintain-Privacy-Gates-in-Three-Modes]]in a deliberate pass.