@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.
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +34 -9
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +25 -0
- package/dist/env-registry.js +69 -7
- package/dist/exec.js +15 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +14 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +40 -0
- package/dist/portal-admin.js +30 -0
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +47 -0
- package/dist/sync-repos.js +80 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +11 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/package.json +2 -2
- package/templates/env.example +33 -23
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
- package/templates/workspace-root/skills/CLAUDE.md +24 -6
- package/templates/workspace-root/skills/README.md +156 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- 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.
|