comber 0.1.0

package/dist/api/driver.js

@@ -0,0 +1,235 @@
+import { operationLabel, parseOpenApi } from "./openapi.js";
+import { buildRequest } from "./request.js";
+import { apiSignal, classifyResponse } from "./classify.js";
+import { ResponseValidator } from "./schema.js";
+import { guardedFetch } from "../core/net.js";
+/** HTTP methods Comber considers safe to fire by default (read-only). */
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** Default transport: the guarded fetch. Egress is fail-closed (private/metadata blocked
+ *  unless `allowPrivateTarget`) and every request has a deadline. Reads the body once. */
+function makeFetchTransport(guard) {
+    return async (req) => {
+        const res = await guardedFetch(req.url, { method: req.method, headers: req.headers, body: req.body }, guard);
+        const headers = {};
+        res.headers.forEach((v, k) => {
+            headers[k.toLowerCase()] = v;
+        });
+        return { status: res.status, headers, bodyText: await res.text() };
+    };
+}
+function headerOf(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers))
+        if (k.toLowerCase() === lower)
+            return v;
+    return undefined;
+}
+const NOOP_COVERAGE = { skip() { }, bumpExtra() { } };
+export class ApiDriver {
+    opts;
+    name = "api";
+    capabilities = { screenshot: false, probes: [] };
+    base;
+    operations;
+    resolver;
+    validator;
+    title;
+    transport;
+    cov = NOOP_COVERAGE;
+    exercised = 0;
+    idorChecks = 0;
+    idorHits = 0;
+    constructor(opts) {
+        this.opts = opts;
+        const parsed = parseOpenApi(opts.doc);
+        this.operations = parsed.operations;
+        this.resolver = parsed.resolver;
+        this.validator = new ResponseValidator(parsed.resolver);
+        this.title = parsed.title;
+        this.base = opts.base.replace(/\/+$/, "");
+        this.transport =
+            opts.transport ?? makeFetchTransport({ allowPrivate: opts.allowPrivateTarget, timeoutMs: opts.timeoutMs });
+    }
+    // -- DriverExtras: the core injects its coverage sink so driver sub-metrics + skips land
+    //    in the one honest ledger the orchestrator owns. --
+    attachCoverage(sink) {
+        this.cov = sink;
+    }
+    async start() {
+        /* stateless — nothing to launch (no browser/session). */
+    }
+    async close() {
+        /* nothing to tear down. */
+    }
+    // -- addressing: the API is ONE catalog state; the base IS the only address. --
+    get entry() {
+        return { id: this.base, scope: this.base, label: this.base };
+    }
+    entryAddress() {
+        return this.entry;
+    }
+    currentAddress() {
+        return this.entry;
+    }
+    inScope(addr) {
+        return addr.id === this.base;
+    }
+    async goto(_addr) {
+        /* single state — navigation is a no-op. */
+    }
+    /** DISCOVER — one Surface, one node per operation. Write methods are surfaced as
+     *  `disabled` in read-only mode so the core counts them as a coverage skip (not a gap). */
+    async snapshot() {
+        const nodes = this.operations.map((op) => ({
+            id: operationLabel(op),
+            kind: "operation",
+            label: operationLabel(op),
+            handle: op,
+            disabled: !SAFE_METHODS.has(op.method) && !this.opts.allowWrites,
+        }));
+        return { address: this.entry, title: this.title, nodes, blindSpots: 0 };
+    }
+    /** EXERCISE — build a concrete request, send it, classify breakage; for auth-required
+     *  operations also fire a no-credential probe to catch an auth bypass. */
+    async exercise(node) {
+        const op = node.handle;
+        // Defense in depth: the core already skips disabled write nodes, but never fire a write
+        // here unless writes are explicitly allowed.
+        if (!SAFE_METHODS.has(op.method) && !this.opts.allowWrites)
+            return {};
+        const req = buildRequest(this.base, op, this.resolver, this.opts.seed);
+        const signals = [];
+        let main;
+        try {
+            main = await this.send(req, true);
+        }
+        catch (e) {
+            this.exercised++;
+            signals.push(apiSignal(op, "request-failed", "warn", `${operationLabel(op)} → transport error: ${errMessage(e)}`, req.url));
+            return { signals };
+        }
+        signals.push(...classifyResponse(op, this.toView(main), req.url, this.resolver, this.validator));
+        // broken-auth: an operation that REQUIRES auth that returns 2xx WITHOUT a credential is
+        // an auth bypass. If a token is configured, fire an explicit no-credential probe; if no
+        // token is configured the main request already carried none, so reuse it.
+        if (op.requiresAuth) {
+            let probe = main;
+            if (this.opts.token) {
+                try {
+                    probe = await this.send(req, false);
+                }
+                catch {
+                    probe = undefined;
+                }
+            }
+            if (probe && probe.status >= 200 && probe.status < 300) {
+                signals.push(apiSignal(op, "broken-auth", "fail", `${operationLabel(op)} requires auth but returned HTTP ${probe.status} WITHOUT credentials (auth bypass)`, req.url));
+            }
+        }
+        // Multi-role cross-tenant object access (IDOR). Opt-in + sandbox-only: only fires for an
+        // operation the operator marked owner-scoped, when >= 2 named auth profiles are configured.
+        signals.push(...(await this.idorProbe(op, req.url)));
+        this.exercised++;
+        return { signals };
+    }
+    /**
+     * IDOR / broken-object-authorization probe. For an owner-scoped operation we take a resource
+     * OWNED by role B (B's role seed), confirm B can actually read it (2xx — so we don't flag a
+     * 404), then re-issue the SAME request with role A's credential. A 2xx for A is a cross-role
+     * object-access break: A reached a resource it does not own. Read-only-by-default still holds
+     * (a write owner-scoped op only reaches here when `allowWrites`, gated at the top of exercise).
+     */
+    async idorProbe(op, where) {
+        const profiles = this.opts.authProfiles ?? [];
+        if (profiles.length < 2 || !this.opts.ownerScoped?.has(operationLabel(op)))
+            return [];
+        const roleSeed = this.opts.roleSeed ?? {};
+        const out = [];
+        for (const owner of profiles) {
+            const ownerReq = buildRequest(this.base, op, this.resolver, roleSeed[owner.role]);
+            let ownerRes;
+            try {
+                ownerRes = await this.sendWithToken(ownerReq, owner.token);
+            }
+            catch {
+                continue;
+            }
+            if (!(ownerRes.status >= 200 && ownerRes.status < 300))
+                continue; // resource absent/not owned
+            for (const accessor of profiles) {
+                if (accessor.role === owner.role)
+                    continue;
+                this.idorChecks++;
+                let accessorRes;
+                try {
+                    accessorRes = await this.sendWithToken(ownerReq, accessor.token);
+                }
+                catch {
+                    continue;
+                }
+                if (accessorRes.status >= 200 && accessorRes.status < 300) {
+                    this.idorHits++;
+                    out.push(apiSignal(op, "broken-object-authorization", "fail", `${operationLabel(op)} → role "${accessor.role}" accessed a resource owned by role "${owner.role}" ` +
+                        `(HTTP ${accessorRes.status}) — IDOR / broken object-level authorization`, where));
+                }
+            }
+        }
+        return out;
+    }
+    /** Send a request through the transport. The Bearer credential is attached only when
+     *  `auth` and a token are present; it is never logged. */
+    async send(req, auth) {
+        const headers = { accept: "application/json", ...req.headers };
+        if (req.bodyContentType)
+            headers["content-type"] = req.bodyContentType;
+        if (auth && this.opts.token)
+            headers["authorization"] = `Bearer ${this.opts.token}`;
+        return this.transport({ method: req.method, url: req.url, headers, body: req.body });
+    }
+    /** Send a request carrying a SPECIFIC role's Bearer credential (the multi-role harness). The
+     *  token is attached as a header only; like all credentials it is never logged. */
+    async sendWithToken(req, token) {
+        const headers = { accept: "application/json", ...req.headers };
+        if (req.bodyContentType)
+            headers["content-type"] = req.bodyContentType;
+        headers["authorization"] = `Bearer ${token}`;
+        return this.transport({ method: req.method, url: req.url, headers, body: req.body });
+    }
+    toView(res) {
+        return { status: res.status, contentType: headerOf(res.headers, "content-type"), bodyText: res.bodyText };
+    }
+    /** No goto-time signals to drain (signals ride the ExerciseResult). */
+    drainSignals() {
+        return [];
+    }
+    /** No visual evidence for an API target. */
+    async screenshot() {
+        return Buffer.alloc(0);
+    }
+    /** No frontier expansion — exhaustiveness is exercising every operation node. */
+    outboundAddresses() {
+        return [];
+    }
+    /** Per-driver structured audit data merged into CrawlResult.extra (counts only — no
+     *  secrets; the base is already surfaced as the redacted startUrl elsewhere). */
+    auditExtra() {
+        const writeOps = this.operations.filter((op) => !SAFE_METHODS.has(op.method)).length;
+        return {
+            apiAudit: {
+                operations: this.operations.length,
+                safeOperations: this.operations.length - writeOps,
+                writeOperations: writeOps,
+                exercised: this.exercised,
+                writesSkipped: this.opts.allowWrites ? 0 : writeOps,
+                allowWrites: this.opts.allowWrites,
+                authProfiles: this.opts.authProfiles?.length ?? 0,
+                ownerScopedOps: this.opts.ownerScoped?.size ?? 0,
+                idorChecks: this.idorChecks,
+                idorHits: this.idorHits,
+            },
+        };
+    }
+}
+function errMessage(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}

package/dist/api/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/api/driver.ts"],"names":[],"mappings":"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"}

package/dist/api/graphql-driver.js

@@ -0,0 +1,150 @@
+import { guardedFetch } from "../core/net.js";
+import { INTROSPECTION_QUERY, buildOperationDocument, graphqlOperationLabel, parseIntrospection, } from "./graphql.js";
+function makeFetchTransport(guard) {
+    return async (req) => {
+        const res = await guardedFetch(req.url, { method: req.method, headers: req.headers, body: req.body }, guard);
+        const headers = {};
+        res.headers.forEach((v, k) => {
+            headers[k.toLowerCase()] = v;
+        });
+        return { status: res.status, headers, bodyText: await res.text() };
+    };
+}
+const NOOP_COVERAGE = { skip() { }, bumpExtra() { } };
+function signatureOf(op, kind) {
+    return `${kind}|${graphqlOperationLabel(op)}`.slice(0, 80);
+}
+export class GraphqlDriver {
+    opts;
+    name = "graphql";
+    capabilities = { screenshot: false, probes: [] };
+    endpoint;
+    transport;
+    schema = { operations: [], typeMap: new Map() };
+    cov = NOOP_COVERAGE;
+    exercised = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.endpoint = opts.endpoint;
+        this.transport =
+            opts.transport ?? makeFetchTransport({ allowPrivate: opts.allowPrivateTarget, timeoutMs: opts.timeoutMs });
+    }
+    attachCoverage(sink) {
+        this.cov = sink;
+    }
+    /** DISCOVER the surface: introspect (over the transport) unless an introspection result was
+     *  supplied, then parse `__schema` into the operation set. */
+    async start() {
+        let introspection = this.opts.introspection;
+        if (introspection === undefined) {
+            const res = await this.post(JSON.stringify({ query: INTROSPECTION_QUERY }));
+            introspection = safeJson(res.bodyText);
+        }
+        this.schema = parseIntrospection(introspection);
+    }
+    async close() {
+        /* stateless */
+    }
+    get entry() {
+        return { id: this.endpoint, scope: this.endpoint, label: this.endpoint };
+    }
+    entryAddress() {
+        return this.entry;
+    }
+    currentAddress() {
+        return this.entry;
+    }
+    inScope(addr) {
+        return addr.id === this.endpoint;
+    }
+    async goto(_addr) {
+        /* single state */
+    }
+    /** One Surface; one node per operation. Mutation (write) nodes are surfaced `disabled` in
+     *  read-only mode so the core counts them as a coverage skip, not a gap. */
+    async snapshot() {
+        const nodes = this.schema.operations.map((op) => ({
+            id: graphqlOperationLabel(op),
+            kind: "graphql-operation",
+            label: graphqlOperationLabel(op),
+            handle: op,
+            disabled: op.kind === "mutation" && !this.opts.allowWrites,
+        }));
+        return { address: this.entry, title: "GraphQL", nodes, blindSpots: 0 };
+    }
+    /** EXERCISE — POST a minimal valid operation document and classify the result. */
+    async exercise(node) {
+        const op = node.handle;
+        // Defense in depth: never send a mutation unless writes are explicitly allowed.
+        if (op.kind === "mutation" && !this.opts.allowWrites)
+            return {};
+        const doc = buildOperationDocument(op, this.schema.typeMap);
+        const signals = [];
+        let res;
+        try {
+            res = await this.post(JSON.stringify({ query: doc }));
+        }
+        catch (e) {
+            this.exercised++;
+            signals.push(this.signal(op, "request-failed", "warn", `${graphqlOperationLabel(op)} → transport error: ${errMessage(e)}`));
+            return { signals };
+        }
+        this.exercised++;
+        if (res.status !== 200) {
+            signals.push(this.signal(op, "graphql-http-status", res.status >= 500 ? "fail" : "warn", `${graphqlOperationLabel(op)} → HTTP ${res.status} (GraphQL normally answers 200)`));
+        }
+        const body = safeJson(res.bodyText);
+        const errors = body && typeof body === "object" ? body.errors : undefined;
+        if (Array.isArray(errors) && errors.length > 0) {
+            const first = errors
+                .slice(0, 3)
+                .map((e) => (e && typeof e === "object" ? String(e.message ?? "error") : String(e)))
+                .join("; ")
+                .slice(0, 160);
+            signals.push(this.signal(op, "graphql-error", "fail", `${graphqlOperationLabel(op)} → GraphQL errors: ${first}`));
+        }
+        return { signals };
+    }
+    signal(op, kind, severity, message) {
+        return { kind, severity, message, url: this.endpoint, signature: signatureOf(op, kind), action: graphqlOperationLabel(op) };
+    }
+    async post(body) {
+        const headers = { accept: "application/json", "content-type": "application/json" };
+        if (this.opts.token)
+            headers["authorization"] = `Bearer ${this.opts.token}`;
+        return this.transport({ method: "POST", url: this.endpoint, headers, body });
+    }
+    drainSignals() {
+        return [];
+    }
+    async screenshot() {
+        return Buffer.alloc(0);
+    }
+    outboundAddresses() {
+        return [];
+    }
+    auditExtra() {
+        const mutations = this.schema.operations.filter((o) => o.kind === "mutation").length;
+        return {
+            graphqlAudit: {
+                operations: this.schema.operations.length,
+                queries: this.schema.operations.length - mutations,
+                mutations,
+                exercised: this.exercised,
+                mutationsSkipped: this.opts.allowWrites ? 0 : mutations,
+                allowWrites: this.opts.allowWrites,
+            },
+        };
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function errMessage(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}

package/dist/api/graphql-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-driver.js","sourceRoot":"","sources":["../../src/api/graphql-driver.ts"],"names":[],"mappings":"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"}

package/dist/api/graphql.js

@@ -0,0 +1,115 @@
+// GraphQL-introspection spec source — the API driver's THIRD discovery mode. Given a GraphQL
+// endpoint we send the standard introspection query, parse `__schema`, and surface the Query
+// and Mutation fields as exercisable operations. No `graphql` dependency: introspection is
+// plain JSON over the wire and a minimal valid operation document is a small string we build
+// from the introspected types. Leaf module — imports nothing from `core`/`web`.
+/** The standard GraphQL introspection query (queries + mutations + the type/enum/input shapes
+ *  we need to synthesize a minimal valid operation document). Trimmed to what the checker uses. */
+export const INTROSPECTION_QUERY = `query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      kind
+      name
+      fields(includeDeprecated: true) { name args { name type { ...TypeRef } } type { ...TypeRef } }
+      inputFields { name type { ...TypeRef } }
+      enumValues(includeDeprecated: true) { name }
+    }
+  }
+}
+fragment TypeRef on __Type {
+  kind name
+  ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } }
+}`;
+function asObject(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+/** Unwrap NON_NULL/LIST wrappers down to the underlying named type ref. */
+function namedRef(t) {
+    let cur = t ?? {};
+    let guard = 0;
+    while (cur && cur.ofType && guard++ < 16)
+        cur = cur.ofType;
+    return cur;
+}
+const isRequired = (t) => t?.kind === "NON_NULL";
+const stripNonNull = (t) => (t.kind === "NON_NULL" && t.ofType ? t.ofType : t);
+/**
+ * Parse an introspection RESULT (`{ data: { __schema } }` or a bare `{ __schema }`) into the
+ * Query+Mutation operations plus a name→type map (for building minimal operation documents).
+ */
+export function parseIntrospection(result) {
+    const root = asObject(result);
+    const data = asObject(root.data ?? root);
+    const schema = asObject(data.__schema);
+    const types = Array.isArray(schema.types) ? schema.types : [];
+    const typeMap = new Map();
+    for (const t of types)
+        if (typeof t?.name === "string")
+            typeMap.set(t.name, t);
+    const queryTypeName = asObject(schema.queryType).name;
+    const mutationTypeName = asObject(schema.mutationType).name;
+    const operations = [];
+    const collect = (typeName, kind) => {
+        if (typeof typeName !== "string")
+            return;
+        const t = typeMap.get(typeName);
+        for (const f of t?.fields ?? []) {
+            // Skip introspection meta-fields if a server lists them.
+            if (f.name.startsWith("__"))
+                continue;
+            operations.push({ kind, name: f.name, args: f.args ?? [], returnType: f.type });
+        }
+    };
+    collect(queryTypeName, "query");
+    collect(mutationTypeName, "mutation");
+    return { operations, typeMap };
+}
+/** A minimal literal satisfying an argument/input-field type (deterministic). */
+function argLiteral(typeRef, typeMap, depth = 0) {
+    const outer = stripNonNull(typeRef);
+    if (outer.kind === "LIST")
+        return "[]"; // an empty list satisfies `[T]` and `[T]!`
+    const named = namedRef(typeRef);
+    const t = named.name ? typeMap.get(named.name) : undefined;
+    switch (named.name) {
+        case "Int":
+        case "Float":
+            return "1";
+        case "Boolean":
+            return "true";
+        case "ID":
+        case "String":
+            return JSON.stringify("sample");
+    }
+    if (t?.kind === "ENUM")
+        return t.enumValues?.[0]?.name ?? "null"; // enum literals are unquoted
+    if (t?.kind === "INPUT_OBJECT") {
+        if (depth >= 4)
+            return "{}";
+        const required = (t.inputFields ?? []).filter((f) => isRequired(f.type));
+        return `{${required.map((f) => `${f.name}: ${argLiteral(f.type, typeMap, depth + 1)}`).join(", ")}}`;
+    }
+    return JSON.stringify("sample"); // custom scalar — best effort
+}
+/**
+ * Build a minimal VALID operation document for `op`: include only the REQUIRED (NON_NULL) args
+ * with synthesized literals, and request `{ __typename }` when the return type is composite (an
+ * object/interface/union needs a sub-selection); scalars/enums take no selection set.
+ */
+export function buildOperationDocument(op, typeMap) {
+    const required = op.args.filter((a) => isRequired(a.type));
+    const argStr = required.length
+        ? `(${required.map((a) => `${a.name}: ${argLiteral(a.type, typeMap)}`).join(", ")})`
+        : "";
+    const named = namedRef(op.returnType);
+    const rt = named.name ? typeMap.get(named.name) : undefined;
+    const composite = rt?.kind === "OBJECT" || rt?.kind === "INTERFACE" || rt?.kind === "UNION";
+    const selection = composite ? " { __typename }" : "";
+    return `${op.kind} { ${op.name}${argStr}${selection} }`;
+}
+/** "query me" / "mutation createUser" — stable operation identity (node id/label, dedupe ns). */
+export function graphqlOperationLabel(op) {
+    return `${op.kind} ${op.name}`;
+}

package/dist/api/graphql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.js","sourceRoot":"","sources":["../../src/api/graphql.ts"],"names":[],"mappings":"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"}