@netlify/agent-runner-cli 2.7.0 → 2.8.0

package/dist/skills/netlify-access-control/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: netlify-access-control
+description: 'Picks the right Netlify site-protection layer and disambiguates the three unrelated "auth" concepts users conflate — app-user login (Netlify Identity), site-load gating (Password Protection / project visibility), and dashboard SAML SSO. Use it when asked to password-protect a site or Deploy Preview, make a project private/public, restrict a site to your team, require SSO to view a site, set up company-wide app SSO, or invite users to a private project. Also use it for SSO-session symptoms on protected sites: "logged out mid-session", 401s after about an hour, or token expiry/refresh questions. Not for wiring auth code — route app-login setup to netlify-identity.'
+---
+
+# Netlify access control — pick the protection layer
+
+This skill routes you to the correct protection layer. It does not teach each one. **These settings have no public API, CLI command, or MCP tool.** Never curl `api.netlify.com` or read local auth tokens to inspect or change them — give the user the dashboard path and checklist. On failure, report what you tried and stop.
+
+## First: disambiguate "auth" — three unrelated layers
+
+Users constantly conflate these. Identify which one is meant before recommending anything.
+
+1. **Netlify Identity** — "who is this user *inside my app*." Issues `nf_jwt`. → route to the **netlify-identity** skill; not covered here.
+2. **Password Protection / project visibility** — "can this request load the site at all." Covered here.
+3. **Team/Org SAML SSO** — "can you log in to the Netlify *dashboard*." Gates dashboard access; also underlies team-login site protection.
+
+Sessions are separate. The same provider (e.g. Google) can appear twice unrelated — Identity OAuth for app users vs. SAML IdP for team members.
+
+**Double-login footgun:** a Password-Protection/team-login perimeter session and an Identity app session have **no bridge** — no shared cookie, no header forwarding, no JWT exchange. Don't try to wire them together. For the combined layered pattern and its tradeoffs, see `references/two-layer-pattern.md`.
+
+**Want company-wide app SSO with a single sign-in (no double login)?** Recommend the **Auth0 extension** federating to the corporate IdP *before* the two-layer stack.
+
+## Decision guide (this skill's job)
+
+- Restrict entire site to your team, invite by email → **Private project** (Credit-based) or **Team login protection** (Password Protection).
+- Share with anyone holding one shared password → **Basic password protection** (Pro) or **Password** visibility (Pro, Credit-based).
+- Keep production public, protect previews only → scope **Previews only** / **Non-production deploys only**.
+- Require SSO to *view a site* → Organization/Team SSO with **Only SSO allowed (strict)**, then Password Protection with **Team login protection**.
+- Protect specific pages/sections with multiple passwords → **Basic authentication with custom HTTP headers** (formerly Selective password protection): https://docs.netlify.com/manage/security/secure-access-to-sites/basic-authentication-with-custom-http-headers/
+- Authenticate your own end users → **Netlify Identity** / **OAuth provider tokens** / **Role-based access control with JWT** → route to netlify-identity.
+- Block malicious/automated traffic or AI crawlers → **Advanced Web Security** (WAF / Firewall Traffic Rules / rate limiting) or **User Agent Blocker** extension: https://docs.netlify.com/build/build-with-ai/block-ai-crawlers/
+
+## Key distinction: Private vs Password
+
+- **Private** already requires Netlify credentials — no shared password. Invite by email; recommended for team-only access.
+- **Password** = one universal shared password anyone can use (including managing team members, who must also enter it). No SSO.
+- **Team login protection** = same mechanism as Private: a visitor must log in as a member of your Netlify team, and **Reviewers** you invite can get in too (unlimited and not counted toward the member count on legacy plans; Pro or higher on Credit-based plans). **Git Contributors cannot log in** — invite them as Reviewers rather than upgrading them to Developer.
+
+## SSO-session symptom: 401s after ~1 hour
+
+If a user reports being "logged out mid-session" or 401s on an SSO-protected site: **SSO auth tokens expire after 1 hour**, after which requests return `401`. Sites with SSO protection return the header **`Netlify-Site-Protection-Expires-In`** — seconds until the request's token expires. Refresh proactively:
+
+```js
+// Client-side. Checks the Netlify SSO protection header and reloads before expiry.
+const res = await fetch(window.location.href, { method: "HEAD" });
+const secondsLeft = Number(res.headers.get("Netlify-Site-Protection-Expires-In"));
+// Tokens last 1 hour (3600s). Reload a bit early to avoid a 401.
+if (!Number.isNaN(secondsLeft) && secondsLeft < 60) {
+  window.location.reload();
+}
+```
+
+## UI paths (the only path — no API)
+
+**Credit-based plans (Free, Personal, Pro)** — project-level "Password Protection" is replaced by **Project visibility**:
+- Per project: Project configuration > General > Visitor access > **Project visibility** — `https://app.netlify.com/projects/{site_name}/configuration/general/#project-visibility`. Edit visibility → (Customize if a team default exists) → **Public** / **Password** (Pro only) / **Private** → set **Preview access** (Production and previews / Previews only) → Save.
+- Team default: Team settings > General > Visitor access > **Default project visibility** — `https://app.netlify.com/teams/{team_name}/settings/general#default-project-visibility`. Options: Private for new projects / Private for all projects / Public for new projects.
+- No per-team default *password* here; set a password per project.
+
+**Enterprise / Open Source / legacy (non-Credit-based)** — use **Password Protection** UI:
+- Per site: Project configuration > General > Visitor access > **Password Protection** — `https://app.netlify.com/projects/{site_name}/configuration/general#visitor-access`. Configure → Basic or Team login → scope (All deploys / Non-production deploys only) → Save.
+- Team default: Team settings > Access & security > Visitor access > **Default Password Protection settings** — `https://app.netlify.com/teams/{team_name}/settings/access#default-site-protection-settings`. Applies to all sites without their own settings.
+
+**Legacy → Credit-based mapping:** No protection→Public · Basic protection→Password · Team protection→Private · All deploys→Production and previews · Non-production deploys only→Previews only.
+
+## Constraints & footguns
+
+- **Site-specific Password Protection overrides team defaults.**
+- **Who can change these settings:** project visibility — Organization Owners (on certain Enterprise plans), Team Owners, and Developers with access to that project; **Internal Builders cannot publish to production, so they cannot make a project public**. Password Protection — a Developer changes it per site, a Team Owner sets the team default.
+- **Advanced Web Security runs before password/login prompts** — a blocked IP hits an error page before ever seeing the prompt. Internal order: Firewall Traffic Rules → WAF → Rate limiting.
+- **Third-party webhooks (Slack, Stripe, etc.) cannot reach a private project** — receiving webhooks requires the project to be **public**.
+- **Make public** requires at least one successful **production deploy**.
+- **Protecting only non-production deploys** with Password Protection is **Enterprise only**.
+- **Plan gating:** Basic password protection for the whole site → all Pro plans; all Password Protection options → Enterprise. Project visibility (public/private, private-by-default) → Credit-based Free/Personal/Pro only; password-protected visibility → Pro only. On Free/Personal a private project is visible only to the Team Owner (single-seat); Pro allows unlimited members.
+- **Team default changes by creation date:** teams created on/after **July 28, 2026** default to **Private for new projects**; earlier teams default to **Public**.
+- **Renamed:** "site-wide password protection" (old name of a Password Protection option); "Selective password protection" → Basic authentication with custom HTTP headers.
+
+Reference: https://docs.netlify.com/manage/security/secure-access-to-sites/overview/ · https://docs.netlify.com/manage/security/secure-access-to-sites/password-protection/ · https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/
+
+<!-- Advanced Web Security (WAF, Firewall Traffic Rules, rate limiting) specifics — limits, config keys, plan gating — not in source; referenced by URL only. -->
+<!-- Exact per-tier matrix of basic vs team-login options across plans is only partially stated in sources. -->
+
+<!-- system: agent-context/access-control/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (access-control)
+
+These are org conventions, not docs facts — merged into the rendered skill by
+ctx-gen and never generated. Owned by the skills maintainer.
+
+1. This is a routing/disambiguation skill: keep it narrow — its job is
+   picking the right protection layer, not teaching each one.
+2. The combined Password-Protection + Identity pattern lives in this skill's
+   `references/two-layer-pattern.md`.
+3. "Auth" on Netlify is three unrelated layers users constantly conflate:
+   Netlify Identity ("who is this user inside my app" — issues `nf_jwt`),
+   Password Protection / project visibility ("can this request load the site
+   at all"), and Team/Org SAML SSO ("can you log in to the Netlify
+   dashboard"). Sessions are separate; the same provider (Google) can appear
+   in two unrelated places — Identity OAuth for app users, SAML IdP for team
+   members. Disambiguate before recommending anything.
+4. The double login is real: a Password-Protection/team-login perimeter
+   session and an Identity app session have no bridge — no shared cookie, no
+   header forwarding, no JWT exchange. Don't burn iterations wiring them
+   together; tradeoffs live in `references/two-layer-pattern.md`.
+5. These settings have no public API, CLI command, or MCP tool. Never curl
+   `api.netlify.com` or read local auth tokens to inspect or change them —
+   hand the user the dashboard path and checklist; on failure, report what
+   you tried and stop.
+6. Identity setup, auth code, and OAuth providers for app users belong to the
+   netlify-identity skill — route there; this skill only picks the layer.
+7. For company-wide app-level SSO with a single sign-in (no double login),
+   the Auth0 extension — federating to the corporate IdP — is the
+   recommendation before the two-layer stack.
+8. The description's triggers must include the SSO-session symptoms users
+   actually report — "logged out mid-session", 401s on an SSO-protected
+   site, token expiry/refresh — not only setup phrasing. The
+   `Netlify-Site-Protection-Expires-In` guidance is unreachable if the
+   skill never triggers on the symptom.
+9. Team login protection excludes Git Contributors, and the answer to that is
+   **Reviewers**, never a Developer seat. Reviewers can open team-login-
+   protected deploys: unlimited and not counted toward the member count on
+   legacy plans, Pro or higher on Credit-based plans. Every answer about Git
+   Contributor access must name the Reviewer path — recommending an upgrade to
+   Developer sells a paid seat per person to solve something the product
+   already solves for free. Stating the exclusion without the remedy is the
+   failure mode this rule exists to prevent; it has happened. Never frame the
+   permitted roles as a closed list ("only X, Y and Z get in") — even with the
+   Reviewer path added after it, a closed list reads as Reviewers being shut
+   out, and agents repeat it. Naming roles is optional; the question is
+   usually only about Git Contributors.
+10. Say who can change these settings, not only how to change them. Project
+   visibility: Organization Owners (on certain Enterprise plans), Team Owners,
+   and Developers with access to that project — and Internal Builders cannot
+   make a project public, because they cannot publish to production. Password
+   Protection: a Developer per site, a Team Owner for the team default. A
+   checklist handed to someone without the role is a dead end.

package/dist/skills/netlify-access-control/references/two-layer-pattern.md

@@ -0,0 +1,69 @@
+# Two-Layer Pattern: Company-Only Access + Per-User Identity
+
+A common enterprise ask conflates two concerns:
+
+1. **Perimeter** — the deployed app should be reachable only by company employees.
+2. **In-app identity** — the app should tell users apart (per-user data, roles).
+
+These are different layers (see the main skill). Below are the four ways to satisfy them on Netlify, ordered from least to most friction, plus why the naive "stack both" approach forces a double login.
+
+## Option A — Invite-only Netlify Identity (best default for "just my team")
+
+Enable Netlify Identity in **invite-only** registration mode and invite only company addresses. Identity becomes the perimeter *and* the in-app identity: no uninvited user can sign in, and every signed-in user is a real Identity user with `nf_jwt` and roles.
+
+- **Plans:** all (free).
+- **Logins:** one.
+- **Per-user identity:** full (roles via `app_metadata`, role-based redirects via `nf_jwt`).
+- **Tradeoffs:** manual invite management; no automatic provisioning from a corporate directory; relies on invite links not being shared. Great for internal tools and small teams; doesn't scale cleanly to thousands of employees.
+
+## Option B — Auth0 extension (best for a real org with an existing IdP)
+
+Use the Netlify **Auth0 extension** instead of (or alongside) Identity. Configure Auth0 to federate with the company's IdP (Okta, Entra, Google Workspace, etc.). Auth0 enforces "company-only" via its connection/organization settings and supplies per-user identity — in a **single** sign-in.
+
+- **Plans:** Auth0 extension (enterprise-oriented); more setup than Identity.
+- **Logins:** one (federated SSO).
+- **Per-user identity:** full, from the corporate directory; supports auto-provisioning.
+- **Tradeoffs:** more moving parts than Identity; requires Auth0 configuration. This is the path when invite-only Identity won't scale. Configured via the Netlify Auth0 extension — see the Netlify docs setup guide for Auth0.
+
+## Option C — Basic Password Protection + Netlify Identity
+
+Put a shared-password gate in front of the site (Pro+) and run Identity inside for per-user accounts. The password keeps the public out; Identity differentiates users.
+
+- **Plans:** Pro+ for the password gate.
+- **Logins:** two (shared password, then Identity) — but the first is a single shared secret, not a per-user login, so it's lighter than Option D.
+- **Use when:** "keep the public out while we build" plus real user accounts, without an Enterprise plan.
+- **Tradeoffs:** the shared password is not per-user and is easily forwarded; it's a soft gate, not real access control.
+
+## Option D — Enterprise team-login perimeter + Netlify Identity (the genuine two-layer, double login)
+
+Enable Team/Org SAML SSO and Password Protection with **team login** (optionally "Only SSO allowed (strict)"), then run Netlify Identity separately for app sessions.
+
+- **Plans:** Enterprise.
+- **Logins:** **two** — the CDN-edge perimeter (company SSO) *and* the app's Identity login.
+- **Per-user identity:** full, in-app via Identity.
+- **Tradeoffs:** the double login (below) and a hidden seat cost — **team login admits only Netlify team members, so every employee who passes it needs a paid Netlify seat.** Choose this only when a true CDN-edge perimeter is a hard requirement and the double login is acceptable.
+
+## Why the double login can't be wired away (today)
+
+When the perimeter gate and Identity are both active, the two sessions are independent:
+
+- The perimeter (Password Protection / SAML SSO) authenticates a **Netlify team member** and issues its own session (SSO tokens via this path expire after ~1 hour).
+- Netlify Identity authenticates an **app end user** and issues the `nf_jwt` cookie.
+
+There is **no documented passthrough** — no shared cookie, no forwarded header, no JWT exchange — that turns "passed the perimeter" into "logged in to the app." A perimeter session also represents *team-member* identity, not an app *end-user* record with `app_metadata.roles`, so even a hypothetical bridge wouldn't cleanly become the app's user.
+
+> An unofficial `netlify/netlify-plugin-identity-sso` repo once attempted a bridge, but it is unofficial, dormant (last release 2021), and hardcoded for `@netlify.com` emails. Don't build on it.
+
+Practical takeaway: if single sign-on matters, pick Option A or B. Don't spend iterations trying to fuse the two layers in Option D — it isn't supported.
+
+## What an agent can and can't see
+
+While writing code, an agent **cannot** read whether Identity is enabled, which OAuth providers are configured, or whether Password Protection / SSO is on — none of it is exposed by the Netlify API, CLI, or MCP server; it lives in the dashboard. The one runtime exception is the live Identity provider list:
+
+```typescript
+import { getSettings } from '@netlify/identity'
+// Returns autoconfirm, disableSignup, and providers — read this from the running app
+const settings = await getSettings()
+```
+
+`getSettings()` hits `/.netlify/identity/settings` and works against any origin serving the page — including localhost under `netlify dev`, which proxies to the live service — so it helps the running app render the right buttons. It does not help at authoring time (before the app runs), so ask the user what's already configured rather than guessing, and hand off any dashboard changes with an explicit checklist.