@glintbase/scanner-core 3.3.0 → 3.5.0

package/README.md

@@ -1,61 +1,61 @@
-# @glintbase/scanner-core
-
-The **ARS 3.2** (Agent Readiness Score) engine behind [scan.glintbase.dev](https://scan.glintbase.dev), packaged for reuse.
-It contains the live probes, the check registry, archetype classification, scoring and grade bands, the URL
-policy (SSRF guards) and the MCP live prober. The [Glintbase CLI](https://github.com/athertech/glintbase-cli)
-(`@glintbase/cli`) scores with this package, so a CLI audit and a web scan of the same site use the same rules.
-
-- ESM only, Node.js 20+, no runtime dependencies (uses the global `fetch`).
-- Type declarations included.
-- Every scorecard carries `version` (`ars-3.2.0`): never compare scores across score versions.
-
-## Install
-
-```bash
-npm install @glintbase/scanner-core
-```
-
-## Usage
-
-```ts
-import { runArs3Probes, validateScanUrl, getAllChecks, ARS_SCORE_VERSION } from '@glintbase/scanner-core';
-
-const policy = validateScanUrl('example.com', { allowHttp: false });
-if (!policy.ok) throw new Error(policy.message);
-
-const scorecard = await runArs3Probes(policy.url!);
-console.log(scorecard.score, scorecard.grade, scorecard.version); // e.g. 78 'B' 'ars-3.2.0'
-console.log(`${scorecard.evidence?.checksEvaluated}/${getAllChecks().length} checks measured`);
-```
-
-Main exports:
-
-| Area | Exports |
-| --- | --- |
-| Scoring | `runArs3Probes`, `runArs3ProbesDetailed`, `runArs2Probes`, `RunProbesOptions`, `Ars3Scorecard`, `CheckResult`, `LayerScoreSummary`, `ScanEvidenceSummary`, `RemediationSummary` |
-| Registry | `ALL_CHECKS`, `getAllChecks`, `getCheckById`, `getChecksForLayer`, `getBonusChecks`, `getChecksForSpec`, `CheckDefinition` |
-| Re-checks | `parseCheckIds`, `partitionCheckIds`, `recheckFromResults`, `unknownCheckResult` |
-| Archetypes | `classifyArchetype`, `normalizeArchetypeOverride`, `ArchetypeProfile` |
-| Bands | `scoreBand`, `scoreBandLabel`, `getArsGrade`, `SCORE_BANDS`, `ARS_GRADE_BANDS` |
-| URLs | `validateScanUrl`, `normalizeUrl`, `registrableDomain`, `brandFromHostname`, `deriveCompanySlug` |
-| Network | `fetchResource`, `probeMcpServer`, `inspectOpenApi` |
-| Full pipeline | `runScan`, `ScanResult`, `formatScanMarkdown` |
-| Versions | `GLINTBASE_VERSION`, `ARS_SCORE_VERSION`, `ARS_LABEL` |
-
-`fetchResource` (and therefore every probe) applies the URL policy before any network I/O: private, loopback
-and metadata addresses and non-standard ports are refused.
-
-## Development
-
-The source is not duplicated here: `src/index.ts` re-exports `../src/lib/scanner` through the `@scanner`
-alias and tsup bundles it into `dist/`.
-
-```bash
-npm install
-npm run typecheck
-npm run build
-```
-
-## License
-
-Apache-2.0
+# @glintbase/scanner-core
+
+The **ARS 3.3** (Agent Readiness Score) engine behind [scan.glintbase.dev](https://scan.glintbase.dev), packaged for reuse.
+It contains the live probes, the check registry, archetype classification, scoring and grade bands, the URL
+policy (SSRF guards) and the MCP live prober. The [Glintbase CLI](https://github.com/athertech/glintbase-cli)
+(`@glintbase/cli`) scores with this package, so a CLI audit and a web scan of the same site use the same rules.
+
+- ESM only, Node.js 20+, no runtime dependencies (uses the global `fetch`).
+- Type declarations included.
+- Every scorecard carries `version` (`ars-3.3.0`): never compare scores across score versions.
+
+## Install
+
+```bash
+npm install @glintbase/scanner-core
+```
+
+## Usage
+
+```ts
+import { runArs3Probes, validateScanUrl, getAllChecks, ARS_SCORE_VERSION } from '@glintbase/scanner-core';
+
+const policy = validateScanUrl('example.com', { allowHttp: false });
+if (!policy.ok) throw new Error(policy.message);
+
+const scorecard = await runArs3Probes(policy.url!);
+console.log(scorecard.score, scorecard.grade, scorecard.version); // e.g. 78 'B' 'ars-3.3.0'
+console.log(`${scorecard.evidence?.checksEvaluated}/${getAllChecks().length} checks measured`);
+```
+
+Main exports:
+
+| Area | Exports |
+| --- | --- |
+| Scoring | `runArs3Probes`, `runArs3ProbesDetailed`, `runArs2Probes`, `RunProbesOptions`, `Ars3Scorecard`, `CheckResult`, `LayerScoreSummary`, `ScanEvidenceSummary`, `RemediationSummary` |
+| Registry | `ALL_CHECKS`, `getAllChecks`, `getCheckById`, `getChecksForLayer`, `getBonusChecks`, `getChecksForSpec`, `CheckDefinition` |
+| Re-checks | `parseCheckIds`, `partitionCheckIds`, `recheckFromResults`, `unknownCheckResult` |
+| Archetypes | `classifyArchetype`, `normalizeArchetypeOverride`, `ArchetypeProfile` |
+| Bands | `scoreBand`, `scoreBandLabel`, `getArsGrade`, `SCORE_BANDS`, `ARS_GRADE_BANDS` |
+| URLs | `validateScanUrl`, `normalizeUrl`, `registrableDomain`, `brandFromHostname`, `deriveCompanySlug` |
+| Network | `fetchResource`, `probeMcpServer`, `inspectOpenApi` |
+| Full pipeline | `runScan`, `ScanResult`, `formatScanMarkdown` |
+| Versions | `GLINTBASE_VERSION`, `ARS_SCORE_VERSION`, `ARS_LABEL` |
+
+`fetchResource` (and therefore every probe) applies the URL policy before any network I/O: private, loopback
+and metadata addresses and non-standard ports are refused.
+
+## Development
+
+The source is not duplicated here: `src/index.ts` re-exports `../src/lib/scanner` through the `@scanner`
+alias and tsup bundles it into `dist/`.
+
+```bash
+npm install
+npm run typecheck
+npm run build
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -4,11 +4,11 @@
  * rule sets are never compared as if they were equivalent.
  */
 /** Product version shared by the web app, CLI and MCP packages. */
-declare const GLINTBASE_VERSION = "3.3.0";
+declare const GLINTBASE_VERSION = "3.5.0";
 /** Scoring model version stamped on every scan result (score_version). */
-declare const ARS_SCORE_VERSION: "ars-3.2.0";
+declare const ARS_SCORE_VERSION: "ars-3.3.0";
 /** Human-readable name of the current scoring model. */
-declare const ARS_LABEL = "ARS 3.2";
+declare const ARS_LABEL = "ARS 3.3";
 declare function isCurrentArsVersion(version?: string | null): boolean;
 /** Any ARS 3.x scan (3.0, 3.1, 3.2, ...). */
 declare function isArs3Version(version?: string | null): boolean;
@@ -100,11 +100,14 @@ interface CheckDefinition {
     description: string;
     remediationId?: string;
 }
+/** What kind of evidence a check rests on; see probes/measurement.ts. */
+type CheckMeasurement = 'live' | 'content' | 'presence' | 'declared';
 interface CheckResult {
     checkId: string;
     name?: string;
     layer?: LayerId;
     status: CheckStatus;
+    measurement?: CheckMeasurement;
     earnedPoints: number;
     maxPoints: number;
     isBonus: boolean;
@@ -137,6 +140,13 @@ interface ScanEvidenceSummary {
     /** Verified base points / registered base points across applicable layers (0-1). */
     baseCoverage: number;
     lowConfidenceLayers: LayerId[];
+    /** The homepage served a bot challenge or HTTP 403; checks derived from it are `skip` ("not observed"). */
+    homepageBlocked?: boolean;
+}
+/** A failure that stops a plain-fetch agent outright; any gate caps the score (see GATE_SCORE_CAP). */
+interface ScoreGate {
+    checkId: string;
+    reason: string;
 }
 interface RemediationSummary {
     id: string;
@@ -192,6 +202,10 @@ interface Ars3Scorecard {
     pillars?: {
         discoverability: ArsPillarSummary;
         runtimeErgonomics: ArsPillarSummary;
+        /** Runtime pillar from `live` and `content` base checks only (no presence, no bonus). */
+        runtimeMeasured?: ArsPillarSummary & {
+            checksCounted: number;
+        };
     };
     layers: {
         discovery: LayerScoreSummary;
@@ -202,6 +216,9 @@ interface Ars3Scorecard {
     results: CheckResult[];
     remediations: RemediationSummary[];
     evidence?: ScanEvidenceSummary;
+    /** Failed gates. When non-empty, `score` is capped and `uncappedScore` holds the weighted result. */
+    gates?: ScoreGate[];
+    uncappedScore?: number;
     criticalVulnerabilities?: CriticalVulnerability[];
     simulation?: SimulationResult;
     durationMs?: number;
@@ -210,7 +227,7 @@ interface Ars3Scorecard {
 }
 
 /**
- * ARS 3.0 Layer 1 Probe: Discovery (16 Checks | 20 Base Pts)
+ * ARS 3.3 Layer 1 Probe: Discovery
  * Evaluates robots.txt AI policy, ARD/Agent-Card catalogs, Wikidata P856,
  * MCP registry branding, agent rules, and package listings.
  */
@@ -245,6 +262,9 @@ interface DiscoveryProbeResult {
 interface AccessProbeResult {
     /** False when the homepage request got no HTTP response at all (DNS/TLS/connect failure or timeout). */
     targetReachable: boolean;
+    /** The homepage served a bot challenge or HTTP 403 to the scanner, so its content was not observed. */
+    homepageBlocked?: boolean;
+    homepageStatus?: number;
     score: number;
     baseEarned: number;
     bonusEarned: number;
@@ -269,7 +289,7 @@ interface AccessProbeResult {
         found: boolean;
         url?: string;
         version?: string;
-        /** Parsed document when the spec is JSON; YAML specs are detected but not parsed. */
+        /** Parsed document (JSON or YAML). Undefined only when a YAML spec failed to parse. */
         spec?: any;
     };
 }
@@ -446,7 +466,6 @@ interface RunProbesOptions {
 /** Below this share of verified base points a layer is flagged lowConfidence. */
 declare const MIN_LAYER_COVERAGE = 0.5;
 declare function runArs3Probes(url: string, options?: RunProbesOptions): Promise<Ars3Scorecard>;
-/** Same as runArs3Probes, but also returns each layer's raw probe output. */
 declare function runArs3ProbesDetailed(url: string, options?: RunProbesOptions): Promise<{
     scorecard: Ars3Scorecard;
     discovery: DiscoveryProbeResult;
@@ -460,8 +479,8 @@ declare function runArs3ProbesDetailed(url: string, options?: RunProbesOptions):
 declare function runArs2Probes(url: string, archetypeInput?: Partial<ArchetypeInput>): Promise<Ars2Scorecard>;
 
 /**
- * ARS 3.2 Central Check Registry
- * Specification: GLINTBASE_AUDIT_3_0_UPGRADE_SPEC.md, methodology: docs/methodology/ars-3.2.md
+ * ARS 3.3 Central Check Registry
+ * Specification: GLINTBASE_AUDIT_3_0_UPGRADE_SPEC.md, methodology: docs/methodology/ars-3.3.md
  * Single source of truth for each check's points and bonus status (count: getAllChecks().length).
  */
 
@@ -629,14 +648,6 @@ declare function fetchResource(url: string, options?: FetchResourceOptions): Pro
 /** True if URL is reachable (GET), including auth walls. */
 declare function verifyUrlExists(url: string | null, timeoutMs?: number): Promise<boolean>;
 
-/**
- * 4-Step Empirical MCP Live Prober (SPEC-09 / ARS 3.1)
- * Evaluates production MCP servers across:
- * 1. Dual Wire-Form Handshake (2026-07-28 in _meta/headers vs legacy)
- * 2. Anonymous Tools Discovery & Hidden Auth Gates
- * 3. Safe Execution Probe & Schema Honesty
- * 4. Error Channel Integrity (isError: true vs 200 string masquerade)
- */
 interface McpProbeStepResult {
     step: 'handshake' | 'tools_list' | 'safe_call' | 'error_channel';
     passed: boolean;
@@ -649,9 +660,14 @@ interface McpProbeStepResult {
 interface McpLiveProbeResult {
     live: boolean;
     endpoint: string;
-    /** initialize returned a JSON-RPC result on either wire form. */
+    /** The server completed a handshake (server/discover result or initialize result). */
     handshakeAccepted: boolean;
+    /** `modern` answered server/discover; `legacy` completed initialize. */
+    era?: 'modern' | 'legacy';
     protocolVersion?: string;
+    /** Revisions a modern server lists in its DiscoverResult. */
+    supportedVersions?: string[];
+    /** Modern server that also completed a legacy initialize handshake. */
     dualWireCompatible: boolean;
     wireForm2026Supported: boolean;
     legacyWireSupported: boolean;
@@ -662,7 +678,7 @@ interface McpLiveProbeResult {
     toolCount: number;
     /** True only when tools/list returned a well-formed tools array. */
     toolsListed: boolean;
-    /** Server capabilities from the initialize result (prompts, resources, logging, ...). */
+    /** Server capabilities from the handshake result (prompts, resources, logging, ...). */
     capabilities: Record<string, any>;
     /** Raw WWW-Authenticate header when the endpoint answered 401. */
     wwwAuthenticate?: string;
@@ -681,12 +697,16 @@ interface McpLiveProbeResult {
         /** inputSchema is an object schema whose properties all declare a type. */
         schemaStrict: boolean;
         declaredRequiredCount: number;
+        /** `$schema` declared on inputSchema, if any (MCP's default dialect is JSON Schema 2020-12). */
+        schemaDialect?: string;
     }>;
+    /** Characters in the serialized tool definitions from the first tools/list page. */
+    toolDefinitionChars: number;
     steps: McpProbeStepResult[];
     reliabilityScore: number;
 }
 /**
- * Executes the 4-step MCP live diagnostic probe against an endpoint.
+ * Executes the dual-era MCP live diagnostic probe against an endpoint.
  */
 declare function probeMcpServer(endpointUrl: string): Promise<McpLiveProbeResult>;
 
@@ -732,6 +752,24 @@ declare function isJsonMediaType(mediaType: string): boolean;
 declare function jsonMediaOf(content: any): any;
 declare function inspectOpenApi(spec: any): OpenApiInspection;
 
+/**
+ * Glintbase Bundled MCP Skills (ARS 3.3)
+ *
+ * Comprehensive suite of 8 production-grade playbooks delivered tri-modally:
+ * 1. MCP Resources (skill://glintbase/<name>)
+ * 2. MCP Prompts (optimize_<name>)
+ * 3. MCP Tools (glintbase_get_skill / glintbase_install_skill)
+ */
+interface BundledSkill {
+    name: string;
+    title: string;
+    description: string;
+    uri: string;
+    tags: string[];
+    content: string;
+}
+declare const BUNDLED_SKILLS: Record<string, BundledSkill>;
+
 type SurfaceType = 'landing' | 'docs' | 'api' | 'sdk' | 'github' | 'support' | 'blog' | 'changelog' | 'status' | 'auth' | 'dashboard' | 'openapi' | 'llms_txt' | 'llms_full_txt' | 'sitemap' | 'mcp';
 interface DiscoveredSurface {
     type: SurfaceType;
@@ -1019,4 +1057,4 @@ interface SpecParseResult {
  */
 declare function parseSpec(url: string, type: SpecType): Promise<SpecParseResult>;
 
-export { ALL_CHECKS, ARS_GRADE_BANDS, ARS_LABEL, ARS_SCORE_VERSION, type AccessProbeResult, type ArchetypeInput, type ArchetypeOverride, type ArchetypeProfile, type Ars2Scorecard, type Ars3Scorecard, type ArsGrade, type ArsPillarSummary, CANONICAL_ARCHETYPES, type CanonicalArchetype, type CheckDefinition, type CheckKind, type CheckRemediation, type CheckResult, type CheckStatus, type CheckTier, type CriticalVulnerability, type DiscoveryProbeResult, type EvaluatorMode, type FetchResourceOptions, type FetchResourceResult, type FetchStatus, GLINTBASE_VERSION, type GradeBand, type LayerId, type LayerScoreSummary, type LayerWeightConfig, MIN_LAYER_COVERAGE, type McpLiveProbeResult, type McpProbeStepResult, type OpenApiInspection, type OpenApiOperationRef, type PaymentsProbeResult, type ReachabilityResult, type RecheckResult, type RemediationSummary, type RunProbesOptions, type RunScanHooks, SCORE_BANDS, type ScanEvidenceSummary, type ScanOptions, type ScanProgressEvent, type ScanResult, type ScoreBand, type ScoreBandKey, type SimulationResult, type SiteArchetype, type SpecParseResult, type SpecType, type UrlPolicyCode, type UrlPolicyResult, type UsabilityProbeResult, badgeColorForScore, brandFromHostname, checkReachability, classifyArchetype, deriveCompany, deriveCompanySlug, fetchResource, formatScanMarkdown, getAllChecks, getArsGrade, getBonusChecks, getCheckById, getChecksForLayer, getChecksForSpec, inspectOpenApi, isArs3Version, isCurrentArsVersion, isJsonMediaType, jsonMediaOf, listOperations, normalizeArchetypeOverride, normalizeUrl, parseCheckIds, parseSpec, partitionCheckIds, policyToErrorCode, probeMcpServer, recheckFromResults, registrableDomain, runArs2Probes, runArs3Probes, runArs3ProbesDetailed, runScan, scoreBand, scoreBandColorHex, scoreBandLabel, scoreBandTextClass, sseHasJsonData, unknownCheckResult, validateScanUrl, verifyUrlExists };
+export { ALL_CHECKS, ARS_GRADE_BANDS, ARS_LABEL, ARS_SCORE_VERSION, type AccessProbeResult, type ArchetypeInput, type ArchetypeOverride, type ArchetypeProfile, type Ars2Scorecard, type Ars3Scorecard, type ArsGrade, type ArsPillarSummary, BUNDLED_SKILLS, type BundledSkill, CANONICAL_ARCHETYPES, type CanonicalArchetype, type CheckDefinition, type CheckKind, type CheckRemediation, type CheckResult, type CheckStatus, type CheckTier, type CriticalVulnerability, type DiscoveryProbeResult, type EvaluatorMode, type FetchResourceOptions, type FetchResourceResult, type FetchStatus, GLINTBASE_VERSION, type GradeBand, type LayerId, type LayerScoreSummary, type LayerWeightConfig, MIN_LAYER_COVERAGE, type McpLiveProbeResult, type McpProbeStepResult, type OpenApiInspection, type OpenApiOperationRef, type PaymentsProbeResult, type ReachabilityResult, type RecheckResult, type RemediationSummary, type RunProbesOptions, type RunScanHooks, SCORE_BANDS, type ScanEvidenceSummary, type ScanOptions, type ScanProgressEvent, type ScanResult, type ScoreBand, type ScoreBandKey, type SimulationResult, type SiteArchetype, type SpecParseResult, type SpecType, type UrlPolicyCode, type UrlPolicyResult, type UsabilityProbeResult, badgeColorForScore, brandFromHostname, checkReachability, classifyArchetype, deriveCompany, deriveCompanySlug, fetchResource, formatScanMarkdown, getAllChecks, getArsGrade, getBonusChecks, getCheckById, getChecksForLayer, getChecksForSpec, inspectOpenApi, isArs3Version, isCurrentArsVersion, isJsonMediaType, jsonMediaOf, listOperations, normalizeArchetypeOverride, normalizeUrl, parseCheckIds, parseSpec, partitionCheckIds, policyToErrorCode, probeMcpServer, recheckFromResults, registrableDomain, runArs2Probes, runArs3Probes, runArs3ProbesDetailed, runScan, scoreBand, scoreBandColorHex, scoreBandLabel, scoreBandTextClass, sseHasJsonData, unknownCheckResult, validateScanUrl, verifyUrlExists };