@installagent/sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/dist/agent-templates.d.ts +36 -2
  2. package/dist/agent-templates.js +173 -3
  3. package/dist/client-linear-create.d.ts +26 -0
  4. package/dist/client-linear-create.js +46 -0
  5. package/dist/client-linear.d.ts +28 -9
  6. package/dist/client-linear.js +36 -14
  7. package/dist/docs-search.d.ts +19 -6
  8. package/dist/docs-search.js +32 -11
  9. package/dist/doctor.d.ts +9 -0
  10. package/dist/doctor.js +126 -23
  11. package/dist/env-fill.d.ts +13 -0
  12. package/dist/env-fill.js +34 -9
  13. package/dist/env-push.d.ts +3 -0
  14. package/dist/env-push.js +11 -6
  15. package/dist/env-registry.d.ts +25 -0
  16. package/dist/env-registry.js +69 -7
  17. package/dist/exec.js +15 -2
  18. package/dist/index.d.ts +14 -6
  19. package/dist/index.js +14 -6
  20. package/dist/linear-project.d.ts +2 -2
  21. package/dist/linear-project.js +2 -2
  22. package/dist/log.d.ts +28 -0
  23. package/dist/log.js +73 -0
  24. package/dist/n8n-executions.d.ts +85 -0
  25. package/dist/n8n-executions.js +259 -0
  26. package/dist/op-cli.d.ts +29 -0
  27. package/dist/op-cli.js +52 -0
  28. package/dist/platform.d.ts +35 -0
  29. package/dist/platform.js +39 -0
  30. package/dist/portal-admin.d.ts +40 -0
  31. package/dist/portal-admin.js +30 -0
  32. package/dist/standup.d.ts +88 -0
  33. package/dist/standup.js +235 -0
  34. package/dist/sync-repos.d.ts +47 -0
  35. package/dist/sync-repos.js +80 -0
  36. package/dist/template-sync.d.ts +10 -0
  37. package/dist/template-sync.js +11 -0
  38. package/dist/wizard.d.ts +15 -0
  39. package/dist/wizard.js +35 -56
  40. package/dist/workspace-docs.d.ts +44 -0
  41. package/dist/workspace-docs.js +73 -0
  42. package/package.json +2 -2
  43. package/templates/env.example +33 -23
  44. package/templates/workspace-root/AGENT.md +7 -5
  45. package/templates/workspace-root/ONBOARDING.md +65 -8
  46. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
  47. package/templates/workspace-root/skills/CLAUDE.md +24 -6
  48. package/templates/workspace-root/skills/README.md +156 -0
  49. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  50. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  51. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  52. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  53. package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
  54. package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
  55. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  56. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
  57. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  58. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  59. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  60. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  61. package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
  62. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  63. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  64. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  65. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  66. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  67. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  68. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  69. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  70. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  71. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  72. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  73. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  74. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  75. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  76. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  77. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  78. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  79. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  80. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -0,0 +1,158 @@
1
+ ---
2
+ name: slack-voice
3
+ description: >-
4
+ Write Slack messages the Install Agent team will actually read: terse, factual,
5
+ bulleted, hard numbers, no prose paragraphs. Use this WHENEVER you are about to
6
+ send or draft a Slack message, DM, or channel post — a status update, a PR
7
+ notification, a question for a teammate, a client-channel reply, a stand-up
8
+ note, "tell Angello X", "post an update in #team-techs", "dm Koz", "let the
9
+ team know". Reach for it even if the user never says "skill": any time the
10
+ output is going into Slack, this is the skill. It exists because a ~400-word
11
+ DM on 2026-08-11 got the reply "Bro, can we please use english" and "I will not
12
+ read all this everytime". Length is not thoroughness in Slack — it is a
13
+ delivery failure. INTERNAL Slack only — team channels and teammate DMs. For a
14
+ Slack message a CLIENT will read, use house-voice instead; its Slack section
15
+ is the client register (greeting, bullets, explicit ask, warmth) and it wins
16
+ there. Does NOT apply to repo docs, evidence/ files, commit bodies, PR
17
+ descriptions, or Linear issues; those stay detailed.
18
+ ---
19
+
20
+ > **Which skill applies.** Internal teammate → this file. Client → `house-voice`
21
+ > § *Slack, specifically*. The registers are different on purpose: a client gets
22
+ > a greeting and an explicit ask; Angello gets a link and a number.
23
+
24
+ # Skill: slack-voice
25
+
26
+ **Use when:** anything you write is going into Slack.
27
+
28
+ ## The bar
29
+
30
+ Angello, after being sent a long DM, wrote the message he wanted instead:
31
+
32
+ > **Pull request here: `<Link>`**
33
+ >
34
+ > "That is 3 words and a link."
35
+
36
+ Koz, same thread: *"you should just respond with the X emoji."*
37
+
38
+ Three words and a link is a complete, correct Slack message. Start there and
39
+ add only what carries information.
40
+
41
+ ## Rules
42
+
43
+ 1. **Lead with the link or the number.** No preamble. The first line is the
44
+ payload.
45
+ 2. **30 words per sentence, maximum.** Count them. Most should be under 15.
46
+ 3. **Bullets, not paragraphs.** One fact per bullet. Cut any clause that
47
+ explains why.
48
+ 4. **Every claim carries a figure.** `18 of 19 checks pass`, `0 client cells
49
+ touched`, `6 days left`. A number can be checked. A description cannot.
50
+ 5. **No adjectives, no adverbs, no fillers.** Delete: *solid, clean, robust,
51
+ healthy, significant, comprehensive, nicely, properly, actually, basically,
52
+ just, really, quite, worth noting, in good shape.* If a number cannot replace
53
+ the word, delete the sentence.
54
+ 6. **No jargon.** Write what a reader says out loud, not what the code calls it.
55
+ "Two approvals at once both write" — not "`allocate` returns `reused:true`
56
+ before `assertStillOurs()`". Keep an identifier only when the reader needs it
57
+ to search: `PR #8`, `INS-202`, a file name, a branch.
58
+ 7. **No reasoning, no hedging, no advocacy.** Cut "I think", "arguably", "where
59
+ I'd still push". State the conclusion. Link the argument.
60
+ 8. **No section headers in a short message.** Bold labels and `###` are what
61
+ make a message read as a wall. One bold first line is the maximum.
62
+ 9. **Ask one question, not three.** Three answers means three messages.
63
+ 10. **Draft before sending to a channel.** Show the user first when the audience
64
+ is the team or a client. A DM to the user themselves can go direct.
65
+
66
+ ## Sending something over
67
+
68
+ Put the thing in the message. Put the context in the thread.
69
+
70
+ - **Message:** what it is, one line, plus the link or file path.
71
+ - **Thread reply:** why it exists, what changed, what you want back.
72
+
73
+ This keeps the channel scannable. Someone who only needs the link stops at the
74
+ first message. Someone who needs the detail opens the thread.
75
+
76
+ ## Shape that works
77
+
78
+ ```
79
+ **<Subject> — <state in three words>**
80
+
81
+ <link>
82
+ <link> — <who owns it>
83
+
84
+ - <fact with a number>
85
+ - <fact with a number>
86
+ - <fact with a number>
87
+
88
+ Open:
89
+ - <thing> — <number or state>. <owner or when>.
90
+
91
+ <one line: what happens next>
92
+ ```
93
+
94
+ ## Before and after
95
+
96
+ Real, from 2026-08-11.
97
+
98
+ **Before** — sent, and got "can we please use english":
99
+
100
+ > Hey — ran a full end-to-end audit of the two Medearis CO/PO workflows on
101
+ > n8n.installagent.com today. Plumbing is in good shape: happy path, single-use
102
+ > link enforcement, all the refusal paths, and the owner-block guard all pass.
103
+ > Three things for you. **1. Your Data Tables question is answered — they work.**
104
+ > You'd flagged on 08-07 that it wasn't established whether… *(continues for
105
+ > ~350 more words)*
106
+
107
+ **After** — same information, sent to `#team-techs`, landed well:
108
+
109
+ > **Medearis CO/PO approval spine — running end to end**
110
+ >
111
+ > Diagrams, both workflows: `<link>`
112
+ > PR #8: `<link>` — Angello reviewing
113
+ >
114
+ > - 18 of 19 checks pass. Real requests at the live service, no mocks.
115
+ > - An approval link works once. The second use is refused.
116
+ > - Intake cannot write to the budget. Approval is the only path that can.
117
+ > - 0 client budget cells touched. Every write hit our own copy.
118
+ >
119
+ > Open:
120
+ > - Two approvals at once both write. No double charge. Fix after 08-17.
121
+ > - Cost-code fix sits in PR #8, not deployed yet.
122
+ > - Failure alerts — INS-202, deferred.
123
+ >
124
+ > Before 08-17: merge PR #8.
125
+
126
+ What was cut: every adjective, every justification, the answer to a question
127
+ nobody re-asked, and three paragraphs of reasoning that belonged in the
128
+ `evidence/` file the message could have linked to.
129
+
130
+ The sent version still carried jargon — `410 on reuse`, `schedule_not_warmed`,
131
+ `allocate` — which rule 6 now removes. Compare the two bullets:
132
+
133
+ | Sent | Better |
134
+ |---|---|
135
+ | Approval links are single-use: commit once, 410 on reuse. | An approval link works once. The second use is refused. |
136
+ | Unwired project holds as `schedule_not_warmed`. | A project we have not set up yet stops, and says why. |
137
+
138
+ ## Channel rules that still apply
139
+
140
+ - **`#client-*` channels have the client in them.** DM for internal review.
141
+ See the workspace memory on shared client channels.
142
+ - **No dollar amounts, billing splits, or contract values** in shared channels
143
+ or Linear. Reference scope by name or phase.
144
+ - **Never one client's data in another client's context.**
145
+ - **Never a real credential, key, or password** — not even to say it leaked.
146
+
147
+ ## Where detail still belongs
148
+
149
+ Slack is the notification layer, not the record. Depth goes in:
150
+
151
+ | Content | Home |
152
+ |---|---|
153
+ | Findings, numbers, method | `evidence/<date>-<what>.md` |
154
+ | What shipped | `docs/00-delivery-log.md` |
155
+ | The argument for a decision | the Linear issue |
156
+ | Why a change is safe | the commit body / PR description |
157
+
158
+ Link to those from Slack instead of restating them.
@@ -0,0 +1,337 @@
1
+ ---
2
+ name: sso-gated-client-app
3
+ description: >-
4
+ Stand up an internal web app for a client — a dashboard, map, worklist, or
5
+ review screen — that only that client's staff can open, using Google Workspace
6
+ SSO on a Next.js app deployed to Vercel. Covers the two-layer auth gate
7
+ (middleware/proxy for pages + an independent session check inside every API
8
+ route), the hosted-domain check that actually restricts sign-in, the
9
+ narrower email allowlist for extra-sensitive data, and the four failure modes
10
+ that all look like "it works" while the app is wide open: a missing
11
+ AUTH_SECRET failing OPEN rather than closed, a proxy matcher that swallows
12
+ API routes and hands fetch() an HTML login page, a dev bypass wired to a
13
+ custom env var instead of NODE_ENV, and a deployed app whose Vercel env vars
14
+ were never set. Use this WHENEVER an engagement produces a screen a client
15
+ logs into — "build them a dashboard", "host the map", "an internal tool for
16
+ their team", "put it behind their Google login", "only their staff should see
17
+ this" — and whenever verifying that an already-deployed client app is
18
+ actually gated.
19
+ ---
20
+
21
+ # SSO-gated internal client app
22
+
23
+ Proven on Behavia Therapy's Geo Scheduling Map
24
+ (`clients/client-behaviatherapy/agent-scheduling-map/web/`): Next.js 16 App
25
+ Router + Auth.js (`next-auth@5`) Google provider, restricted to one Workspace
26
+ domain, deployed on Vercel, reading a server-side snapshot.
27
+
28
+ The auth pattern is the reusable part. Every client dashboard we build needs
29
+ exactly this, and it has failed open twice in one build — both times while
30
+ looking completely fine.
31
+
32
+ **The rule this whole document exists to enforce: an auth gate is not done when
33
+ it is written, it is done when it has been `curl`ed against the deployed URL
34
+ with no session.**
35
+
36
+ ---
37
+
38
+ ## Part 1 — Two layers, both required
39
+
40
+ ```
41
+ request
42
+ │
43
+ ├─ page request ──► proxy.ts (middleware) ──► no session? 307 → /signin
44
+ │
45
+ └─ /api/* ────────► NOT touched by the proxy
46
+ └─► the route handler calls await auth() itself
47
+ └─► no session? 401 JSON
48
+ ```
49
+
50
+ Neither layer is sufficient alone. The proxy can't return a sensible error to a
51
+ `fetch()`; the route check can't protect a server-rendered page the user
52
+ navigates to directly.
53
+
54
+ ### The proxy
55
+
56
+ ```ts
57
+ // proxy.ts
58
+ import { NextResponse } from "next/server";
59
+ import { auth } from "./auth";
60
+
61
+ const bypass = process.env.NODE_ENV === "development";
62
+
63
+ export default auth((req) => {
64
+ if (bypass) return;
65
+ if (!req.auth) {
66
+ const signInUrl = new URL("/signin", req.nextUrl.origin);
67
+ signInUrl.searchParams.set("callbackUrl", req.nextUrl.pathname);
68
+ return NextResponse.redirect(signInUrl);
69
+ }
70
+ });
71
+
72
+ export const config = {
73
+ matcher: [
74
+ "/((?!api/|signin|access-denied|_next/static|_next/image|favicon.ico).*)",
75
+ ],
76
+ };
77
+ ```
78
+
79
+ **The `api/` exclusion in the matcher is load-bearing.** If the proxy redirects
80
+ an API route, a client-side `fetch()` — which follows redirects by default —
81
+ receives **HTTP 200 with an HTML sign-in page** where it expected JSON. It
82
+ doesn't throw. It doesn't log. It fails silently, and you debug the wrong
83
+ layer. Found during the Behavia build's own smoke test.
84
+
85
+ `signin` and `access-denied` are excluded for the obvious reason: a signed-out
86
+ user has to be able to reach them.
87
+
88
+ ### The route check
89
+
90
+ ```ts
91
+ // app/api/<thing>/route.ts
92
+ export async function GET() {
93
+ const bypass = process.env.NODE_ENV === "development";
94
+ if (!bypass) {
95
+ const session = await auth();
96
+ if (!session) {
97
+ return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
98
+ }
99
+ }
100
+ return NextResponse.json(await getData());
101
+ }
102
+ ```
103
+
104
+ Do this **even while the app runs on invented data.** The pattern has to be
105
+ correct before the data becomes real, because nobody adds it later — the switch
106
+ to real data is exactly the moment everyone is thinking about something else.
107
+
108
+ ---
109
+
110
+ ## Part 2 — The domain gate
111
+
112
+ ```ts
113
+ // auth.ts
114
+ const ALLOWED_DOMAIN = "clientdomain.com";
115
+
116
+ export const { handlers, auth, signIn, signOut } = NextAuth({
117
+ providers: [Google],
118
+ pages: { signIn: "/signin", error: "/access-denied" },
119
+ callbacks: {
120
+ async signIn({ profile }) {
121
+ const email = profile?.email ?? "";
122
+ const hd = (profile as { hd?: string } | undefined)?.hd;
123
+ const verified = profile?.email_verified === true;
124
+ return (
125
+ verified &&
126
+ hd === ALLOWED_DOMAIN &&
127
+ email.toLowerCase().endsWith(`@${ALLOWED_DOMAIN}`)
128
+ );
129
+ },
130
+ },
131
+ });
132
+ ```
133
+
134
+ Three independent conditions on purpose:
135
+
136
+ - **`hd`** is Google's hosted-domain claim. It is present only for Workspace
137
+ accounts and absent for personal `@gmail.com` — this is the real check.
138
+ - **The email suffix** is a cheaper-to-audit second check, in case a future
139
+ provider config stops requesting or passing `hd`.
140
+ - **`email_verified`** closes the unverified-address case.
141
+
142
+ A personal Google account will complete Google's own sign-in screen and *then*
143
+ get bounced to `/access-denied` by this callback. That's expected, and it's why
144
+ `/access-denied` needs to exist and read like a deliberate page rather than a
145
+ crash.
146
+
147
+ **This check is server-side, on every sign-in.** A client-side domain check is
148
+ decoration.
149
+
150
+ ### The narrower allowlist, for genuinely sensitive data
151
+
152
+ A domain gate means *everyone at the client company*. When the screen shows
153
+ something a company doesn't share internally — patient locations, salary data,
154
+ individual performance — add an explicit email allowlist alongside the domain
155
+ check:
156
+
157
+ ```ts
158
+ const ALLOWLIST = new Set(["named.person@clientdomain.com", /* … */]);
159
+ // inside signIn(): && ALLOWLIST.has(email.toLowerCase())
160
+ ```
161
+
162
+ Rules that keep this honest:
163
+
164
+ - **Confirm the exact list with the client in writing. Never guess names.**
165
+ - **Ship it before the sensitive data lands, not after.** An allowlist added
166
+ the week after real data goes in has already failed.
167
+ - **Removing it is a deliberate event** — tie it to a named condition (a signed
168
+ agreement, a completed review), not a date, and record the condition in the
169
+ build repo's docs so the next technician doesn't widen the gate as cleanup.
170
+
171
+ On Behavia this was the compensating control that made a scoped real-data
172
+ exception acceptable while the client-side agreement was still unsigned. It
173
+ bounds the blast radius; it does not substitute for the paperwork, and the
174
+ decision doc says so explicitly.
175
+
176
+ ---
177
+
178
+ ## Part 3 — Four ways this fails while looking fine
179
+
180
+ ### 1. Missing `AUTH_SECRET` fails **open**
181
+
182
+ Without `AUTH_SECRET`, Auth.js logs an error internally and **does not block
183
+ the request.** The app serves data to anyone. Nothing user-visible looks
184
+ broken.
185
+
186
+ **Treat an unset `AUTH_SECRET` as a hard stop in any deployed environment**,
187
+ not a warning to skim past. Generate with `npx auth secret`; never reuse the
188
+ `.env.example` placeholder.
189
+
190
+ ### 2. Deployed ≠ gated
191
+
192
+ The Behavia app was live on a `.vercel.app` URL while all three auth env vars
193
+ had never been set on the Vercel project — combined with #1, the gate was open
194
+ in production while the repo's README described a working gate.
195
+
196
+ **A deploy is not done until the env vars are set on the deployment and the
197
+ gate is re-verified against the deployed URL.** Two separate steps in the
198
+ checklist, both ticked by evidence.
199
+
200
+ ### 3. A dev bypass wired to a custom env var
201
+
202
+ ```ts
203
+ const bypass = process.env.NODE_ENV === "development"; // ✅
204
+ const bypass = process.env.AUTH_DISABLED === "true"; // ❌ never
205
+ ```
206
+
207
+ `NODE_ENV` is set to `development` by `next dev` and by nothing else —
208
+ `next build`/`next start` and **every** Vercel deployment including previews
209
+ run `production`. It cannot be flipped on live by a missing or typo'd variable.
210
+ A custom flag can. That's the entire argument, and it's why the codebase
211
+ carries a comment forbidding the change.
212
+
213
+ The bypass earns its place: it lets a technician run `pnpm dev` with no OAuth
214
+ client and no secret. Keep it, keep it hardcoded to `NODE_ENV`.
215
+
216
+ ### 4. The redirect URI covers the preview URL but not the real one
217
+
218
+ Add both `https://<final-custom-domain>/api/auth/callback/google` and
219
+ `http://localhost:3000/api/auth/callback/google` to the OAuth client. Sign-in
220
+ that works on `*.vercel.app` and dies on the custom domain is always this.
221
+
222
+ ---
223
+
224
+ ## Part 4 — Provisioning (the client has to do two things)
225
+
226
+ The app cannot reach a working state without someone with cloud access **on the
227
+ client's side**. Put both on `docs/04-access-checklist.md` at kickoff, not at
228
+ deploy time.
229
+
230
+ 1. **A Google OAuth 2.0 Client ID** ("Web application"), created in **a GCP
231
+ project the client owns** — not an Install Agent project. The consent
232
+ screen's **User type must be Internal** (Workspace-only). That alone
233
+ restricts sign-in to their Workspace; the `auth.ts` domain check is the
234
+ code-side second layer on top.
235
+ 2. **DNS for the custom domain** — the client usually controls it. Add the
236
+ domain in Vercel, hand them the record.
237
+
238
+ Then set three Vercel **project** env vars, sourced from the client's 1Password
239
+ vault, never committed:
240
+
241
+ | Var | From |
242
+ |---|---|
243
+ | `AUTH_GOOGLE_ID` | the OAuth client |
244
+ | `AUTH_GOOGLE_SECRET` | the OAuth client |
245
+ | `AUTH_SECRET` | `npx auth secret` |
246
+
247
+ Until both client-side steps exist, the sign-in button fails at **Google's**
248
+ screen (`invalid client`) — not because of anything in the codebase. Say that
249
+ in the repo README so the next person doesn't debug our code for an hour.
250
+
251
+ ---
252
+
253
+ ## Part 5 — Verify, with commands, and paste the output
254
+
255
+ Against the **deployed** URL, signed out:
256
+
257
+ ```bash
258
+ # a page → 307 redirect to /signin
259
+ curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://<app>/
260
+
261
+ # an API route → 401 JSON, NOT a redirect, NOT HTML
262
+ curl -sS -i https://<app>/api/<thing> | head -20
263
+ ```
264
+
265
+ Pass looks like:
266
+
267
+ ```
268
+ 307 https://<app>/signin?callbackUrl=%2F
269
+ HTTP/2 401
270
+ {"error":"Unauthorized"}
271
+ ```
272
+
273
+ If the API route returns `200` with `text/html`, the proxy matcher is
274
+ swallowing it (Part 1). If it returns `200` with your JSON, the gate is open —
275
+ check `AUTH_SECRET` first.
276
+
277
+ Then the human checks a machine can't do:
278
+
279
+ - Sign in with a **personal** Google account → lands on `/access-denied`.
280
+ - Sign in with a client Workspace account **not** on the allowlist (if you have
281
+ one) → `/access-denied`.
282
+ - Have **someone other than the builder** sign in successfully. The builder's
283
+ account is always implicitly fine; it proves nothing.
284
+
285
+ Paste the actual output into the build repo's `docs/00-delivery-log.md` entry.
286
+ "Verified working, not just written" is the standard.
287
+
288
+ ---
289
+
290
+ ## Part 6 — What the app is allowed to hold
291
+
292
+ - **Minimize server-side.** First name plus initial, not full names. Rounded
293
+ coordinates, not addresses. An age integer, not a DOB. Trim in the ingest so
294
+ the sensitive version never exists in the app's reach.
295
+ - **Never bundle the dataset into the page.** It goes through the gated API
296
+ route, always — a dataset inlined into HTML is served before any session
297
+ check the page's own code performs.
298
+ - **Access logging on the data route.** Who fetched, when. Minimum viable is a
299
+ structured log line with the session email and a timestamp.
300
+ - **Read-only by construction.** If the app has no write path, say so in the
301
+ README *and* give the reader a way to verify it (`grep` for `POST`/`PUT`/
302
+ `method:` and see for yourself). A claim someone can check in ten seconds is
303
+ worth more than a paragraph of assurance.
304
+
305
+ ---
306
+
307
+ ## Requirements checklist
308
+
309
+ - [ ] `proxy.ts` protects pages; matcher **excludes** `api/`, `signin`, `access-denied`, `_next/*`
310
+ - [ ] Every API route calls `await auth()` itself and returns 401 JSON
311
+ - [ ] `auth.ts` `signIn` callback checks `email_verified` + `hd` + email suffix
312
+ - [ ] Email allowlist added when the data is sensitive beyond "company-internal", list confirmed in writing
313
+ - [ ] `/signin` and `/access-denied` exist and are reachable signed-out
314
+ - [ ] Dev bypass keyed on `NODE_ENV === "development"` and nothing else
315
+ - [ ] OAuth client created in the **client's** GCP project, consent screen User type = **Internal**
316
+ - [ ] Redirect URIs include the final custom domain **and** localhost
317
+ - [ ] `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` / `AUTH_SECRET` set on the **Vercel project**, from 1Password
318
+ - [ ] `curl` evidence captured for both the 307 and the 401 **on the deployed URL**
319
+ - [ ] Personal-account rejection confirmed by hand
320
+ - [ ] A second person (not the builder) signed in successfully
321
+ - [ ] Access logging on the data route; dataset never bundled into the page
322
+ - [ ] Delivery-log entry with the actual command output
323
+
324
+ ## Known gaps to flag, not silently skip
325
+
326
+ - **Sign-in restriction is not authorization.** Everyone who passes the gate
327
+ sees everything. Per-role or per-record visibility is a separate build — if
328
+ the client says "but managers shouldn't see X", that's scope, not config.
329
+ - **Session revocation is not instant.** Removing someone from the allowlist
330
+ blocks the next sign-in; an existing session survives until it expires.
331
+ Shorten the session lifetime if that gap matters.
332
+ - **The dev bypass means local runs are unauthenticated.** Fine on a laptop,
333
+ never on a shared or tunnelled host (`ngrok`, a preview box). Don't expose a
334
+ `pnpm dev` process to the internet.
335
+ - **Auth.js v5 is still moving.** Pin the version and re-verify the gate after
336
+ any `next-auth` upgrade — the callback contract is the thing most likely to
337
+ shift under you.