@sagentix-inc/evidence-collector 0.3.4 → 0.3.5

package/README.md

@@ -394,6 +394,33 @@ node src/cli.ts run --source lms --training-csv lms-export.csv --roster-csv rost
 | --- | --- |
 | `security_awareness_current` | Everyone on the roster completed security awareness training within 12 months |
 | `role_based_training_current` | People in privileged roles completed role-based training within 12 months |
+
+### Stripe
+
+**Create:** in the Stripe Dashboard (live mode), Developers > API keys > **Create restricted key**, with every permission left at **None** except **Webhook Endpoints: Read**. A secret key (`sk_live_…`, `sk_test_…`) is refused before any request: it can do anything in the account and cannot be narrowed (docs.stripe.com/keys, read 2026-11-02).
+
+**Credentials:** `STRIPE_API_KEY` (`rk_live_…`; an `rk_test_…` sandbox key works and marks each resource "(sandbox)"). The collector calls one endpoint, `GET /v1/webhook_endpoints`, paging with `starting_after`, and sends endpoint ids and URL hosts only, never a path or a signing secret.
+
+Stripe's API does not show team members, their two-step authentication, the API key inventory, key access policies or Radar rules. Those stay manual evidence.
+
+| Check (`stripe.`…) | What passes |
+| --- | --- |
+| `webhooks_https` | Every enabled webhook endpoint receives events over HTTPS |
+| `webhook_events_scoped` | No enabled webhook endpoint subscribes to every event (`*`) |
+
+### Resend
+
+**Create:** in Resend, API Keys > **Create API key** with **Full access**. Resend has no read-only permission, and a **Sending access** key cannot list domains or keys (resend.com/docs/api-reference/api-keys/create-api-key, read 2026-11-02). The collector only sends `GET` to `https://api.resend.com`; give the key a name of its own, keep it in a secrets store, and expire it if the machine that holds it is lost.
+
+**Credentials:** `RESEND_API_KEY` (`re_…`). The collector calls `GET /domains`, `GET /domains/{id}` and `GET /api-keys`, with a User-Agent header as Resend requires, and sends domain names and key ids only: never a key's name or value, nor a DNS record's value.
+
+**Options:** `--resend-key-max-age-days` (default 365), `--resend-inactive-days` (default 90). A domain's TLS mode is not returned by `GET /domains/{id}`, so it is not judged; DMARC is a DNS record Resend does not manage (the `web` source's `--web-mail-domain` reads it).
+
+| Check (`resend.`…) | What passes |
+| --- | --- |
+| `sending_domains_authenticated` | Each sending domain is verified, with every SPF and DKIM record verified |
+| `api_keys_rotated` | Every API key was created within the allowed age |
+| `api_keys_in_use` | Every API key was used in the last 90 days; a key never used fails |
 | `training_records_complete` | Every person on the roster has a training record |
 
 ## Identity and code sources

package/apps/sos-app/src/data/checks/resend.json

@@ -0,0 +1,27 @@
+{
+ "source": "resend",
+ "title": "Resend (REST API, full_access key used for GET only)",
+ "readScopes": [
+  "A Resend API key with full_access (Resend has no read-only permission; a sending_access key cannot list domains or keys). The collector sends GET requests only, to https://api.resend.com."
+ ],
+ "checks": [
+  {
+   "id": "resend.sending_domains_authenticated",
+   "title": "Every Resend sending domain is verified, with its SPF and DKIM records verified",
+   "scope": "Domains whose sending capability is not disabled; the domain status and the status Resend reports for each SPF and DKIM record.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "resend.api_keys_rotated",
+   "title": "Every Resend API key was created within the allowed age (365 days by default)",
+   "scope": "Every API key of the team, by created_at; --resend-key-max-age-days sets the age.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "resend.api_keys_in_use",
+   "title": "Every Resend API key was used in the last 90 days",
+   "scope": "Every API key of the team, by last_used_at; a key never used fails. --resend-inactive-days sets the window.",
+   "evidenceType": "Configuration"
+  }
+ ]
+}

package/apps/sos-app/src/data/checks/stripe.json

@@ -0,0 +1,21 @@
+{
+ "source": "stripe",
+ "title": "Stripe (REST API, restricted key with Webhook Endpoints: Read)",
+ "readScopes": [
+  "A restricted API key (rk_live_...) whose only permission is Webhook Endpoints: Read (Dashboard > Developers > API keys > Create restricted key). A secret key (sk_...) is refused."
+ ],
+ "checks": [
+  {
+   "id": "stripe.webhooks_https",
+   "title": "Every enabled Stripe webhook endpoint receives events over HTTPS",
+   "scope": "The enabled webhook endpoints of the account (or sandbox) the restricted key belongs to; whether the receiver checks the Stripe-Signature header is not visible.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "stripe.webhook_events_scoped",
+   "title": "No enabled Stripe webhook endpoint subscribes to every event",
+   "scope": "enabled_events of each enabled endpoint; '*' (all events, per Stripe's API reference) fails. Which events an endpoint truly needs is not judged.",
+   "evidenceType": "Configuration"
+  }
+ ]
+}

package/apps/sos-app/src/data/checks/vercel.json

@@ -0,0 +1,51 @@
+{
+ "source": "vercel",
+ "title": "Vercel (team-scoped access token; the collector sends GET only)",
+ "readScopes": [
+  "Team-scoped access token (Scope: the team, All Projects), created by a team member whose role can read team settings, members and project settings; Vercel tokens have no read-only setting"
+ ],
+ "checks": [
+  {
+   "id": "vercel.team_saml_enforced",
+   "title": "Team sign-in is enforced through SAML single sign-on",
+   "scope": "Members of the Vercel team; the factors the identity provider asks for are not visible here.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "vercel.team_owners_limited",
+   "title": "At most --vercel-max-owners members are team owners",
+   "scope": "Team-level roles; project-level roles are not counted.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "vercel.activity_log_available",
+   "title": "The team activity log is readable and not empty",
+   "scope": "Vercel's activity events for the team; retention and export are not judged.",
+   "evidenceType": "Audit Record"
+  },
+  {
+   "id": "vercel.deployment_protection",
+   "title": "Deployment Protection covers preview deployments",
+   "scope": "Each project's Vercel Authentication or Password Protection scope; production custom domains may stay public by design.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "vercel.git_fork_protection",
+   "title": "Pull requests from forks need a team member's authorization before they deploy",
+   "scope": "Projects connected to a Git repository.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "vercel.no_plain_secret_envs",
+   "title": "No credential is stored as a plain environment variable",
+   "scope": "Variable names and types only; a credential with an innocent name is not found.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "vercel.firewall_enabled",
+   "title": "The Vercel Firewall is on for the project",
+   "scope": "Each project's firewall switch; the rules it runs are not judged.",
+   "evidenceType": "Configuration"
+  }
+ ]
+}

package/collector/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@sagentix-inc/evidence-collector",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "type": "module"
 }

package/collector/src/sources/index.js

@@ -13,12 +13,16 @@ import { prowler } from "./prowler.js";
 import { ENGINE_SOURCES } from "./engines.js";
 import { DEVICE_SOURCES } from "./device_sources.js";
 import { web } from "./web.js";
+import { vercel } from "./vercel.js";
+import { stripe } from "./stripe.js";
+import { resend } from "./resend.js";
 export const SOURCES = [
     cloudflare,
     entra, okta, jumpcloud, googleWorkspace, github,
-    aws, azure, gcp, jira, lms,
+    aws, azure, gcp, vercel, jira, lms,
     prowler,
     ...ENGINE_SOURCES,
     ...DEVICE_SOURCES,
     web,
+    stripe, resend,
 ];

package/collector/src/sources/resend.js

@@ -0,0 +1,137 @@
+// Resend (transactional email), read-only use of its REST API: the sending domains' authentication and the API
+// keys' age and use. GET only, with RESEND_API_KEY.
+//
+// Resend has no read-only key. Its API key permissions are full_access ("Can create, delete, get, and update any
+// resource") and sending_access ("Can only send emails"), and a sending_access key cannot list domains or keys
+// (resend.com/docs/api-reference/api-keys/create-api-key, read 2026-11-02). So this source needs a full_access key.
+// The collector itself only ever sends GET (fetchRest refuses anything else and any other origin), but the key could
+// do more in other hands: give it a name of its own (for example "Sagentix collector, read only"), keep it in the
+// Keychain or a secrets vault, and expire it if the machine is lost. The checks below then flag it like any other key.
+//
+// Pages and schema, all read 2026-11-02:
+//   resend.com/docs/api-reference/introduction: base https://api.resend.com, "Authorization: Bearer re_xxxxxxxxx", a
+//     User-Agent header on every request (a request without one is refused with 403), 10 requests per second per team
+//     by default, 429 above it.
+//   resend.com/docs/api-reference/domains/list-domains: GET /domains?limit=1..100&after=<id> -> { object: "list",
+//     has_more, data: [ { id, name, status, created_at, region, open_tracking, click_tracking, capabilities: { sending,
+//     receiving } } ] }.
+//   resend.com/docs/api-reference/domains/get-domain: GET /domains/{id} -> the domain with records: [ { record (SPF,
+//     DKIM, Tracking, ...), name, type, ttl, status, value, priority } ].
+//   resend.com/docs/api-reference/api-keys/list-api-keys: GET /api-keys?limit&after -> { has_more, data: [ { id, name,
+//     created_at, last_used_at } ] }; the permission is not returned.
+//   Resend's OpenAPI (github.com/resend/resend-openapi, resend.yaml, info.version 1.5.1, commit 0b2a456): Domain.status
+//     enum pending, verified, failed, not_started, partially_verified, partially_failed; DomainRecord.record enum SPF,
+//     DKIM, Receiving, Tracking, TrackingCAA; DomainRecord.status enum pending, verified, failed, temporary_failure,
+//     not_started. A domain's TLS mode (opportunistic or enforced) can be set (PATCH /domains/{id}) but is not in the
+//     Domain schema GET returns, so no check reads it; DMARC is a DNS record Resend does not manage (the web source's
+//     --web-mail-domain reads it).
+//
+// Results carry domain names and key ids; never a key's name, value or a DNS record's value.
+import { COLLECTOR_VERSION } from "../payload.js";
+import { DAY_MS, Emitter, arr, enc, fetchRest, firstIds, getAll, isObj, listRead, ok, realSleep, redact, str, withRetry, } from "./readonly_http.js";
+import { posNum } from "./report_files.js";
+export const RESEND_CHECKS = ["sending_domains_authenticated", "api_keys_rotated", "api_keys_in_use"];
+export const RESEND_BASE = "https://api.resend.com";
+export const RESEND_ENV = { token: "RESEND_API_KEY" };
+export const RESEND_DEFAULTS = { keyMaxAgeDays: 365, inactiveDays: 90 };
+const UA = `sagentix-evidence-collector/${COLLECTOR_VERSION} (+https://github.com/Sagentix-Advisors-Inc/sagentix-collector)`;
+const PAGE = 100;
+export function resendFromEnv(env, fetchFn = fetch) {
+    const token = env[RESEND_ENV.token];
+    if (!token)
+        return `${RESEND_ENV.token} is not set`;
+    if (!token.startsWith("re_"))
+        return `${RESEND_ENV.token} does not look like a Resend API key (re_...)`;
+    return fetchRest({ base: RESEND_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${token}`, "user-agent": UA }) });
+}
+/** Resend's timestamps look like "2026-04-08 00:11:13.110779+00"; Date.parse wants an ISO 8601 offset. */
+export function resendTime(v) {
+    const s = str(v);
+    if (!s)
+        return undefined;
+    const iso = s.trim().replace(" ", "T").replace(/([+-]\d{2})$/, "$1:00").replace(/(\.\d{3})\d+/, "$1");
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? t : undefined;
+}
+const list = (api, path) => getAll(api, `${path}?limit=${PAGE}`, (b) => (isObj(b) && Array.isArray(b.data) ? b.data : undefined), (r) => {
+    const b = r.body;
+    if (!isObj(b) || b.has_more !== true)
+        return undefined;
+    const last = arr(b.data).filter(isObj).at(-1);
+    return last && str(last.id) ? `${path}?limit=${PAGE}&after=${enc(String(last.id))}` : undefined;
+}, 50);
+export const resend = {
+    name: "resend",
+    options: {
+        "resend-key-max-age-days": { type: "string", help: `largest age of a Resend API key, in days (default ${RESEND_DEFAULTS.keyMaxAgeDays})` },
+        "resend-inactive-days": { type: "string", help: `days without use after which a Resend API key counts as unused (default ${RESEND_DEFAULTS.inactiveDays})` },
+    },
+    emits: RESEND_CHECKS.map((c) => `resend.${c}`),
+    describe: () => "resend team (the API key's)",
+    async run(ctx) {
+        const out = new Emitter("resend", "resend team");
+        const given = ctx.clients.resend;
+        const built = given !== undefined ? given : resendFromEnv(ctx.env);
+        if (!built || typeof built === "string") {
+            out.skipAll(RESEND_CHECKS, typeof built === "string" ? built : `${RESEND_ENV.token} is not set`);
+            return out.results;
+        }
+        const api = withRetry(built, ctx.clients.sleep ?? realSleep);
+        const now = ctx.now.getTime();
+        // Sending domains: verified, with every SPF and DKIM record verified.
+        const doms = await list(api, "/domains");
+        if ("error" in doms)
+            out.skip("sending_domains_authenticated", doms.error, "domains");
+        else {
+            const sending = doms.items.filter(isObj).filter((d) => !isObj(d.capabilities) || d.capabilities.sending !== "disabled");
+            if (!sending.length)
+                out.add("sending_domains_authenticated", "skipped", `${doms.items.length} domain(s), none sending; nothing to judge`, "resend team", listRead(doms));
+            for (const d of sending) {
+                const name = str(d.name) ?? String(d.id);
+                const r = await api.get(`/domains/${enc(String(d.id))}`);
+                if (!ok(r) || !isObj(r.body)) {
+                    out.skip("sending_domains_authenticated", r, `domain ${name}`, `resend domain ${name}`);
+                    continue;
+                }
+                const recs = arr(r.body.records).filter(isObj).filter((x) => x.record === "SPF" || x.record === "DKIM");
+                const bad = recs.filter((x) => x.status !== "verified").map((x) => `${String(x.record)} ${String(x.type ?? "")} ${String(x.status)}`.replace(/\s+/g, " "));
+                const kinds = new Set(recs.map((x) => x.record));
+                const missing = ["SPF", "DKIM"].filter((k) => !kinds.has(k));
+                const status = String(r.body.status ?? d.status);
+                const pass = status === "verified" && !bad.length && !missing.length;
+                out.add("sending_domains_authenticated", pass ? "pass" : "fail", `domain status ${status}; ${recs.length} SPF/DKIM record(s), ${bad.length} not verified${firstIds(bad)}${missing.length ? `; no ${missing.join(" or ")} record listed` : ""}; status verified and every SPF and DKIM record verified required`, `resend domain ${name}`, { method: "config-read", itemsRead: recs.length, complete: true });
+            }
+        }
+        // API keys: age and last use.
+        const keys = await list(api, "/api-keys");
+        if ("error" in keys) {
+            out.skip("api_keys_rotated", keys.error, "API keys");
+            out.skip("api_keys_in_use", keys.error, "API keys");
+        }
+        else {
+            const ks = keys.items.filter(isObj);
+            const read = listRead(keys);
+            if (!ks.length) {
+                out.add("api_keys_rotated", "skipped", "the team has no API key; nothing to judge", "resend team", read);
+                out.add("api_keys_in_use", "skipped", "the team has no API key; nothing to judge", "resend team", read);
+            }
+            else {
+                const maxAge = posNum(ctx.opts["resend-key-max-age-days"], RESEND_DEFAULTS.keyMaxAgeDays);
+                const inactive = posNum(ctx.opts["resend-inactive-days"], RESEND_DEFAULTS.inactiveDays);
+                const old = [], idle = [];
+                for (const k of ks) {
+                    const id = String(k.id);
+                    const created = resendTime(k.created_at);
+                    if (created === undefined || (now - created) / DAY_MS > maxAge)
+                        old.push(created === undefined ? `${id}:unknown age` : `${id}:${Math.floor((now - created) / DAY_MS)}d`);
+                    const used = resendTime(k.last_used_at);
+                    if (used === undefined || (now - used) / DAY_MS > inactive)
+                        idle.push(used === undefined ? `${id}:never used` : `${id}:${Math.floor((now - used) / DAY_MS)}d`);
+                }
+                out.add("api_keys_rotated", old.length ? "fail" : "pass", `${ks.length} API key(s), ${old.length} older than ${maxAge} days${firstIds(old)}; every key created within ${maxAge} days required (--resend-key-max-age-days)`, "resend team", read);
+                out.add("api_keys_in_use", idle.length ? "fail" : "pass", `${ks.length} API key(s), ${idle.length} not used in the last ${inactive} days${firstIds(idle)}; every key used within ${inactive} days required, or expire it (--resend-inactive-days)`, "resend team", read);
+            }
+        }
+        return redact(out.results, [ctx.env[RESEND_ENV.token]]);
+    },
+};

package/collector/src/sources/stripe.js

@@ -0,0 +1,95 @@
+// Stripe, read-only: the webhook endpoints that receive the account's events. GET only, with a RESTRICTED key
+// (rk_live_... or rk_test_...) in STRIPE_API_KEY whose only permission is Webhook Endpoints: Read. A secret key
+// (sk_...) is refused before any request: it "has unrestricted permissions on all Stripe APIs" and cannot be narrowed.
+//
+// Pages, all read 2026-11-02:
+//   docs.stripe.com/keys: key types; restricted keys rk_live_/rk_test_, secret keys sk_live_/sk_test_; Stripe
+//     recommends migrating secret key usage to restricted keys.
+//   docs.stripe.com/keys/restricted-api-keys: per-resource permission None, Read or Write; "GET" maps to read; write
+//     implies read.
+//   docs.stripe.com/api/webhook_endpoints/list (Stripe-Version 2026-10-28.endive on the page): GET /v1/webhook_endpoints
+//     ?limit=1..100&starting_after=<id> -> { object: "list", has_more, data: [ { id, url, status, enabled_events,
+//     livemode, api_version, application } ] }.
+//   Stripe's OpenAPI (github.com/stripe/openapi, openapi/spec3.json, info.version 2026-09-30.endive, commit 51610f5):
+//     webhook_endpoint.status "The status of the webhook. It can be `enabled` or `disabled`."; enabled_events
+//     "`['*']` indicates that all events are enabled, except those that require explicit selection."
+//
+// What the API does not show, and so stays manual evidence: team members and their two-step authentication, the API
+// key inventory, key access policies (docs.stripe.com/keys#access-policies, Dashboard only) and Radar rules.
+// Results carry webhook endpoint ids and URL hosts; never a path, query or signing secret.
+import { Emitter, arr, enc, fetchRest, firstIds, getAll, isObj, listRead, realSleep, redact, str, withRetry, } from "./readonly_http.js";
+export const STRIPE_CHECKS = ["webhooks_https", "webhook_events_scoped"];
+export const STRIPE_BASE = "https://api.stripe.com";
+export const STRIPE_ENV = { token: "STRIPE_API_KEY" };
+const PAGE = 100;
+/** Why a key is refused, or undefined for a restricted key. */
+export function stripeKeyProblem(key) {
+    if (!key)
+        return `${STRIPE_ENV.token} is not set`;
+    if (/^sk_(live|test)_/.test(key))
+        return `${STRIPE_ENV.token} is a secret key (sk_), which can do anything in the account; create a restricted key (rk_) with only Webhook Endpoints: Read`;
+    if (!/^rk_(live|test)_/.test(key))
+        return `${STRIPE_ENV.token} is not a restricted Stripe key (rk_live_ or rk_test_)`;
+    return undefined;
+}
+export function stripeFromEnv(env, fetchFn = fetch) {
+    const key = env[STRIPE_ENV.token];
+    const bad = stripeKeyProblem(key);
+    if (bad)
+        return bad;
+    return fetchRest({ base: STRIPE_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${key}` }) });
+}
+const host = (u) => { try {
+    return new URL(String(u)).host || "(no host)";
+}
+catch {
+    return "(not a URL)";
+} };
+export const stripe = {
+    name: "stripe",
+    options: {},
+    emits: STRIPE_CHECKS.map((c) => `stripe.${c}`),
+    describe: () => "stripe account (the restricted key's)",
+    async run(ctx) {
+        const key = ctx.env[STRIPE_ENV.token];
+        const mode = key?.startsWith("rk_test_") ? " (sandbox)" : "";
+        const out = new Emitter("stripe", `stripe account${mode}`);
+        // The refusal of a secret key holds even when a client is handed in.
+        const keyBad = key !== undefined ? stripeKeyProblem(key) : undefined;
+        if (keyBad) {
+            out.skipAll(STRIPE_CHECKS, keyBad);
+            return redact(out.results, [key]);
+        }
+        const given = ctx.clients.stripe;
+        const built = given !== undefined ? given : stripeFromEnv(ctx.env);
+        if (!built || typeof built === "string") {
+            out.skipAll(STRIPE_CHECKS, typeof built === "string" ? built : `${STRIPE_ENV.token} is not set`);
+            return out.results;
+        }
+        const api = withRetry(built, ctx.clients.sleep ?? realSleep);
+        const got = await getAll(api, `/v1/webhook_endpoints?limit=${PAGE}`, (b) => (isObj(b) && Array.isArray(b.data) ? b.data : undefined), (r) => {
+            const b = r.body;
+            if (!isObj(b) || b.has_more !== true)
+                return undefined;
+            const last = arr(b.data).filter(isObj).at(-1);
+            return last && str(last.id) ? `/v1/webhook_endpoints?limit=${PAGE}&starting_after=${enc(String(last.id))}` : undefined;
+        }, 20);
+        if ("error" in got) {
+            for (const c of STRIPE_CHECKS)
+                out.skip(c, got.error, "webhook endpoints");
+            return redact(out.results, [key]);
+        }
+        const read = listRead(got);
+        const on = got.items.filter(isObj).filter((w) => w.status !== "disabled");
+        if (!on.length) {
+            for (const c of STRIPE_CHECKS)
+                out.add(c, "skipped", `${got.items.length} webhook endpoint(s), none enabled; nothing to judge`, undefined, read);
+            return redact(out.results, [key]);
+        }
+        const plain = on.filter((w) => !String(w.url ?? "").startsWith("https://")).map((w) => `${String(w.id)}:${host(w.url)}`);
+        out.add("webhooks_https", plain.length ? "fail" : "pass", `${on.length} enabled webhook endpoint(s), ${plain.length} not on https${firstIds(plain)}; every endpoint URL on https required`, undefined, read);
+        const all = on.filter((w) => arr(w.enabled_events).includes("*")).map((w) => `${String(w.id)}:${host(w.url)}`);
+        out.add("webhook_events_scoped", all.length ? "fail" : "pass", `${on.length} enabled webhook endpoint(s), ${all.length} subscribed to every event ('*')${firstIds(all)}; each endpoint limited to the events it handles required`, undefined, read);
+        return redact(out.results, [key]);
+    },
+};

package/collector/src/sources/vercel.js

@@ -0,0 +1,195 @@
+// Vercel: a team (or a personal account) and its projects over the REST API (GET only), with an access token
+// in VERCEL_TOKEN. Vercel has no read-only token: a token carries a scope (Full Account, a team with All
+// Projects, or one project) and acts with its creator's role ("How do I use a Vercel API Access Token?",
+// vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token, last updated 2026-10-01, read 2026-11-02). Use a
+// team-scoped token with a short expiration, created by a member with the least role that can read the team's
+// settings; the collector sends GET requests only and never asks Vercel to decrypt a value.
+//
+// Endpoints, each checked on 2026-11-02 in Vercel's OpenAPI (openapi.vercel.sh, info.version 0.0.1, 12,070,294
+// bytes, sha256 8e3342453cdf0a81…) and on its reference page under https://vercel.com/docs/rest-api (the page named
+// below, each last updated 2026-11-02). A team is named with ?teamId=team_… or ?slug=… on every call.
+//   GET /v2/teams/{teamId}                 teams/get-a-team: saml.enforced ("When `true`, interactions with the Team
+//                                          **must** be done with an authentication token that has been authenticated
+//                                          with the Team's SAML Single Sign-On provider"), saml.connection.
+//   GET /v3/teams/{teamId}/members         teams/list-team-members: members[].role (OWNER, MEMBER, DEVELOPER, SECURITY,
+//                                          BILLING, VIEWER, VIEWER_FOR_PLUS, CONTRIBUTOR), members[].uid; pages by
+//                                          ?until=<pagination.next> while pagination.hasNext.
+//   GET /v3/events?limit=1                 user/list-user-events: events[].createdAt, the team's activity log.
+//   GET /v10/projects?limit=100            projects/retrieve-a-list-of-projects: projects[].id/name; ?from=<pagination.next>
+//                                          ("Query only projects updated after the given timestamp or continuation token").
+//   GET /v9/projects/{idOrName}            projects/find-a-project-by-id-or-name: ssoProtection.deploymentType and
+//                                          passwordProtection.deploymentType (all, all_except_custom_domains, preview,
+//                                          prod_deployment_urls_and_all_previews; null when off), gitForkProtection,
+//                                          security.firewallEnabled.
+//   GET /v10/projects/{idOrName}/env       projects/retrieve-the-environment-variables-of-a-project-by-id-or-name:
+//                                          envs[].key and envs[].type (encrypted, plain, secret, sensitive, system).
+//                                          Only key and type are read; `decrypt` is never sent, and no value leaves memory.
+//
+// What the settings mean, read 2026-11-02:
+//   Deployment Protection (vercel.com/docs/deployment-protection, last updated 2026-09-15): every protection scope,
+//     Standard Protection included, covers preview URLs; none set means anyone with a preview URL can open it.
+//   Git Fork Protection (vercel.com/docs/git/vercel-for-github, last updated 2026-09-17): "If you receive a pull request
+//     from a fork of your repository, Vercel will require authorization from you or a team member to deploy".
+//   Vercel WAF (vercel.com/docs/vercel-firewall/vercel-waf, last updated 2026-07-29): "available on all plans".
+//   SAML SSO (vercel.com/docs/saml, last updated 2026-08-28): "available on Enterprise and Pro plans". Two-factor
+//     enforcement for a team exists (vercel.com/docs/two-factor-enforcement, last updated 2026-08-28) but the team
+//     object in the OpenAPI has no field for it, so a team without SAML gets team_saml_enforced skipped, never failed.
+//   The team "Enforce Sensitive Environment Variables" policy is deprecated (last updated 2026-08-28,
+//     https://vercel.com/docs/environment-variables/sensitive-environment-variables), so no check reads it.
+//
+// Personal data: counts and Vercel user ids only, never an email.
+import { Emitter, enc, fetchRest, firstIds, getAll, intOpt, isObj, ok, realSleep, redact, str, withRetry, } from "./readonly_http.js";
+export const VERCEL_BASE = "https://api.vercel.com";
+export const VERCEL_TOKEN_ENV = "VERCEL_TOKEN";
+export const DEFAULTS = { maxOwners: 3, maxProjects: 50 };
+export const TEAM_CHECKS = ["team_saml_enforced", "team_owners_limited", "activity_log_available"];
+export const PROJECT_CHECKS = ["deployment_protection", "git_fork_protection", "no_plain_secret_envs", "firewall_enabled"];
+/** Names that say the value is a credential. A plain variable is shown to anyone who can open the project's settings. */
+export const SECRET_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|API_?KEY|ACCESS_?KEY|SIGNING_?KEY|DATABASE_URL|_DSN$|WEBHOOK)/i;
+export function vercelFromEnv(env, fetchFn = fetch) {
+    const token = env[VERCEL_TOKEN_ENV];
+    if (!token)
+        return `${VERCEL_TOKEN_ENV} is not set`;
+    return fetchRest({ base: VERCEL_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${token}` }) });
+}
+/** The query naming the team: teamId for an id (team_…), slug for anything else; nothing for a personal account. */
+export const teamQuery = (team) => (!team ? "" : /^team_/.test(team) ? `teamId=${enc(team)}` : `slug=${enc(team)}`);
+const withTeam = (path, tq) => (tq ? `${path}${path.includes("?") ? "&" : "?"}${tq}` : path);
+async function teamChecks(api, team, tq, o, out) {
+    const t = await api.get(withTeam(`/v2/teams/${enc(team)}`, tq));
+    if (!ok(t) || !isObj(t.body))
+        out.skip("team_saml_enforced", t, "team");
+    else {
+        const saml = isObj(t.body.saml) ? t.body.saml : undefined;
+        const enforced = saml?.enforced;
+        const connected = !!saml && isObj(saml.connection);
+        if (enforced === true)
+            out.add("team_saml_enforced", "pass", "saml.enforced is true; every sign-in to the team goes through its SAML identity provider");
+        else if (connected)
+            out.add("team_saml_enforced", "fail", "a SAML connection is configured but saml.enforced is not true; members may still sign in without it");
+        else
+            out.add("team_saml_enforced", "skipped", "SAML SSO is not configured (available on Pro and Enterprise); Vercel's REST API does not show the team's two-factor enforcement, so sign-in strength is not judged here");
+    }
+    const members = await getAll(api, withTeam(`/v3/teams/${enc(team)}/members?limit=100`, tq), (b) => (isObj(b) && Array.isArray(b.members) ? b.members : undefined), (r) => {
+        const p = isObj(r.body) && isObj(r.body.pagination) ? r.body.pagination : undefined;
+        const next = p && p.hasNext === true && p.next !== undefined && p.next !== null ? String(p.next) : undefined;
+        return next ? withTeam(`/v3/teams/${enc(team)}/members?limit=100&until=${enc(next)}`, tq) : undefined;
+    }, 20);
+    if ("error" in members)
+        out.skip("team_owners_limited", members.error, "team members");
+    else {
+        const owners = members.items.filter(isObj).filter((m) => m.role === "OWNER").map((m) => String(m.uid ?? "?"));
+        const over = owners.length > o.maxOwners;
+        out.add("team_owners_limited", over ? "fail" : "pass", `${owners.length} owner(s) among ${members.items.length} member(s)${over ? `; user ids${firstIds(owners)}` : ""}; at most ${o.maxOwners} allowed (--vercel-max-owners)${members.truncated ? "; the member list was cut at 20 pages" : ""}`);
+    }
+    const ev = await api.get(withTeam("/v3/events?limit=1", tq));
+    if (!ok(ev) || !isObj(ev.body) || !Array.isArray(ev.body.events))
+        out.skip("activity_log_available", ev, "team activity log");
+    else {
+        const e = ev.body.events[0];
+        const at = isObj(e) && Number.isFinite(Number(e.createdAt)) ? new Date(Number(e.createdAt)).toISOString() : undefined;
+        out.add("activity_log_available", e ? "pass" : "fail", e ? `team activity log readable; latest event at ${at ?? "?"}` : "team activity log readable but empty");
+    }
+}
+const PROTECTED = new Set(["all", "all_except_custom_domains", "preview", "prod_deployment_urls_and_all_previews"]);
+const scopeOf = (v) => (isObj(v) ? str(v.deploymentType) : undefined);
+async function projectChecks(api, id, tq, out) {
+    const p = await api.get(withTeam(`/v9/projects/${enc(id)}`, tq));
+    const res = `vercel project ${id}`;
+    if (!ok(p) || !isObj(p.body)) {
+        for (const c of PROJECT_CHECKS)
+            out.skip(c, p, "project", res);
+        return;
+    }
+    const b = p.body;
+    const name = str(b.name) ?? id;
+    const r = `vercel project ${name}`;
+    const sso = scopeOf(b.ssoProtection), pw = scopeOf(b.passwordProtection);
+    const on = [sso && `Vercel Authentication (${sso})`, pw && `Password Protection (${pw})`].filter(Boolean);
+    const covers = [sso, pw].some((s) => !!s && PROTECTED.has(s));
+    out.add("deployment_protection", covers ? "pass" : "fail", `${on.length ? on.join(", ") : "no Deployment Protection"}; a protection scope that covers preview deployments required`, r);
+    const fork = b.gitForkProtection;
+    if (typeof fork !== "boolean")
+        out.add("git_fork_protection", "skipped", "gitForkProtection is not shown for this project (no Git repository connected?)", r);
+    else
+        out.add("git_fork_protection", fork ? "pass" : "fail", `gitForkProtection is ${fork}; true required, so a pull request from a fork needs a team member's authorization before it deploys`, r);
+    const fw = isObj(b.security) ? b.security.firewallEnabled : undefined;
+    if (typeof fw !== "boolean")
+        out.add("firewall_enabled", "skipped", "security.firewallEnabled is not shown for this project", r);
+    else
+        out.add("firewall_enabled", fw ? "pass" : "fail", `security.firewallEnabled is ${fw}; true required`, r);
+    const env = await api.get(withTeam(`/v10/projects/${enc(id)}/env`, tq));
+    if (!ok(env) || !isObj(env.body) || !Array.isArray(env.body.envs)) {
+        out.skip("no_plain_secret_envs", env, "environment variables", r);
+        return;
+    }
+    const vars = env.body.envs.filter(isObj);
+    const plain = vars.filter((v) => v.type === "plain" && SECRET_NAME.test(String(v.key ?? ""))).map((v) => String(v.key));
+    out.add("no_plain_secret_envs", plain.length ? "fail" : "pass", `${vars.length} environment variable(s), ${vars.filter((v) => v.type === "plain").length} of type plain, ${plain.length} of them named like a credential${firstIds(plain)}; a credential stored as encrypted, sensitive or secret required (names only were read)`, r);
+}
+export async function vercelChecks(api, o, warn = () => { }) {
+    const tq = teamQuery(o.team);
+    const out = new Emitter("vercel", o.team ? `vercel team ${o.team}` : "vercel personal account");
+    if (o.team)
+        await teamChecks(api, o.team, tq, o, out);
+    else
+        out.skipAll(TEAM_CHECKS, "no --vercel-team given; a personal account has no team settings");
+    let ids = o.projects;
+    if (!ids.length) {
+        const l = await getAll(api, withTeam("/v10/projects?limit=100", tq), (b) => (isObj(b) && Array.isArray(b.projects) ? b.projects : Array.isArray(b) ? b : undefined), (r) => {
+            const p = isObj(r.body) && isObj(r.body.pagination) ? r.body.pagination : undefined;
+            const next = p && p.next !== undefined && p.next !== null ? String(p.next) : undefined;
+            return next ? withTeam(`/v10/projects?limit=100&from=${enc(next)}`, tq) : undefined;
+        }, Math.ceil(o.maxProjects / 100) + 1);
+        if ("error" in l) {
+            for (const c of PROJECT_CHECKS)
+                out.skip(c, l.error, "the project list", "vercel project (list)");
+            return out.results;
+        }
+        const all = l.items.filter(isObj).map((p) => String(p.id ?? p.name ?? "?"));
+        if (all.length > o.maxProjects)
+            warn(`vercel: ${all.length} projects; checking the first ${o.maxProjects} (--vercel-max-projects, or name them with --vercel-project)`);
+        ids = all.slice(0, o.maxProjects);
+        if (!ids.length)
+            for (const c of PROJECT_CHECKS)
+                out.add(c, "skipped", "no project the token can see", "vercel project (none)");
+    }
+    for (const id of ids)
+        await projectChecks(api, id, tq, out);
+    return out.results;
+}
+const listOpt = (v) => (Array.isArray(v) ? v : typeof v === "string" ? [v] : []).flatMap((s) => String(s).split(",")).map((s) => s.trim()).filter(Boolean);
+export const vercel = {
+    name: "vercel",
+    options: {
+        "vercel-team": { type: "string", help: "Vercel team id (team_…) or slug; omit for a personal account (team checks are then skipped)" },
+        "vercel-project": { type: "string", multiple: true, help: "project id or name; default: every project the token can see" },
+        "vercel-max-projects": { type: "string", help: `projects checked when none is named (default ${DEFAULTS.maxProjects})` },
+        "vercel-max-owners": { type: "string", help: `team owners allowed (default ${DEFAULTS.maxOwners})` },
+    },
+    emits: [...TEAM_CHECKS, ...PROJECT_CHECKS].map((c) => `vercel.${c}`),
+    describe(opts) {
+        const t = typeof opts["vercel-team"] === "string" ? `team ${opts["vercel-team"]}` : "personal account";
+        const p = listOpt(opts["vercel-project"]);
+        return `${t} / ${p.length ? `projects ${p.join(",")}` : "every project"}`;
+    },
+    async run(ctx) {
+        const team = typeof ctx.opts["vercel-team"] === "string" && ctx.opts["vercel-team"].trim() ? ctx.opts["vercel-team"].trim() : undefined;
+        const given = ctx.clients.vercel;
+        const built = given !== undefined ? given : vercelFromEnv(ctx.env);
+        if (!built || typeof built === "string") {
+            const out = new Emitter("vercel", team ? `vercel team ${team}` : "vercel personal account");
+            const reason = typeof built === "string" ? built : "no Vercel client";
+            out.skipAll(TEAM_CHECKS, reason);
+            out.skipAll(PROJECT_CHECKS, reason, "vercel project (none)");
+            return out.results;
+        }
+        const api = withRetry(built, ctx.clients.sleep ?? realSleep);
+        const o = {
+            team, projects: listOpt(ctx.opts["vercel-project"]),
+            maxOwners: intOpt(ctx.opts["vercel-max-owners"], DEFAULTS.maxOwners),
+            maxProjects: intOpt(ctx.opts["vercel-max-projects"], DEFAULTS.maxProjects),
+        };
+        return redact(await vercelChecks(api, o, ctx.warn), [ctx.env[VERCEL_TOKEN_ENV]]);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentix-inc/evidence-collector",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Customer-side evidence collector: reads systems read-only, runs checks, signs the results and pushes them outbound to sos-app.",
   "type": "module",
   "engines": {