{"openapi":"3.1.0","info":{"title":"pkgproof","version":"1.0.0","summary":"Verify an npm package before installing it.","description":"A package-verification oracle for npm. Returns one verdict backed by evidence reasons, each labelled fact or heuristic with its source, and fails loud rather than vouch for a package it could not check.","contact":{"name":"pkgproof","email":"support@pkgproof.net","url":"https://pkgproof.net/docs"},"license":{"name":"Proprietary","identifier":"LicenseRef-proprietary"},"x-guidance":"POST /v1/verify with a JSON body of {\"ecosystem\":\"npm\",\"name\":\"left-pad\",\"version\":\"1.3.0\"} to check one npm package before installing it. `version` is optional and defaults to the latest published one. The answer is one of safe, caution, block, does_not_exist, with every reason attached and labelled fact or heuristic against its source, so an agent can act on the verdict alone or read the reasons. Every call on this host is paid: an unpaid one is refused with the 402 and its terms. A paid call costs $0.05 settled with x402 on algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=; a 402 is the ordinary first response and carries the terms to sign. There is no account, no API key and no signup."},"servers":[{"url":"https://x402-algo.pkgproof.net","description":"Paid endpoint. Answers 402 until an x402 payment is presented."}],"externalDocs":{"url":"https://pkgproof.net/docs","description":"Docs"},"security":[{"x402Payment":[]}],"paths":{"/v1/verify":{"post":{"operationId":"verifyPackage","summary":"Verify one package","description":"Runs up to 8 checks in order and returns the worst verdict any produced, with every reason attached. Stops early on a terminal verdict, so block and does_not_exist carry fewer reasons than a completed pipeline; both are answers and return 200. Costs $0.05, settled with x402 on algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=.","x-payment-info":{"price":{"currency":"USD","mode":"fixed","amount":"0.05"},"protocols":[{"x402":{"x402Version":2,"scheme":"exact","network":"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=","asset":"31566704","payTo":"NE3HBSH4MZLCJ3G5UPYBTIHGRCQ5M7K5N2ROWCBK6EQFR62FEROLBVQTTQ","maxAmountRequired":"50000","maxTimeoutSeconds":60,"extra":{"tag":"x402-global-challenge"}}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"A completed verification. The verdict may be safe, caution, block, does_not_exist. A result is reused for 1 hour: an identical request inside that window returns the stored verification with its original `checked_at`, without re-running the checks. Always paid on this host. A free daily verification is offered on another host and is described at https://pkgproof.net/docs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"invalid_json: The request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"payment_identity_missing: The request reached the origin carrying no payment identity. free_quota_exhausted: Today's free verification has already been used, or the service's daily free allowance is gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: The request did not arrive through the paid Worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"method_not_allowed: Anything other than POST on /v1/verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"payment_already_used: This authorisation was already spent. One authorisation buys one verification. payment_claim_in_flight: This payer already has a verification running. The authorisation is unspent; resend it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid_request: A missing or malformed name, ecosystem, or version. unsupported_ecosystem: An ecosystem other than npm.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"upstream_error: A required data source could not be reached. No verdict is issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"upstream_timeout: The verification exceeded its wall-clock budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"VerifyRequest":{"type":"object","required":["ecosystem","name"],"additionalProperties":false,"properties":{"ecosystem":{"type":"string","enum":["npm"]},"name":{"type":"string","maxLength":214,"pattern":"^(?:@[a-zA-Z0-9][\\w.-]*/)?[a-zA-Z0-9][\\w.-]*$","description":"ASCII only. Homoglyph and Unicode-confusable names are rejected before any upstream call."},"version":{"type":"string","maxLength":64,"pattern":"^[\\w.+-]+$","description":"Optional. Omit to verify the package rather than a specific release."}}},"Verification":{"type":"object","required":["ecosystem","name","verdict","reasons","sources","checked_at"],"properties":{"ecosystem":{"type":"string","enum":["npm"]},"name":{"type":"string"},"version":{"type":["string","null"]},"verdict":{"$ref":"#/components/schemas/Verdict"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/Reason"}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"The upstream each check consulted, by name."},"checked_at":{"type":"string","format":"date-time","description":"When this verification ran, which is not always when it was requested; a reused result carries its original timestamp."}}},"Verdict":{"type":"string","enum":["safe","caution","block","does_not_exist"],"description":"Ordered worst-last: safe < caution < block < does_not_exist. The overall verdict is the worst any check produced."},"Reason":{"type":"object","required":["verdict","code","kind","source","detail"],"x-reason-codes":{"does_not_exist":["package_not_found","version_not_found"],"block":["malicious_package","malicious_install_script","likely_slopsquat"],"caution":["registry_security_hold","version_removed","known_vulnerability","install_scripts_present","suspicious_install_script","possible_typosquat","possible_combosquat","possible_scope_confusion","possible_dependency_confusion","repository_impersonation","suspicious_publication_timeline","dormant_package_resurrected"],"safe":["package_exists","no_known_advisories","no_install_scripts","install_scripts_not_evaluated","no_typosquat_match","typosquat_recognized_package","typosquat_not_evaluated","no_combosquat_match","combosquat_recognized_package","combosquat_not_evaluated","no_scope_confusion","scope_recognized_package","scope_not_evaluated","source_repository_present","no_source_repository","repository_not_evaluated","reputation"]},"properties":{"verdict":{"$ref":"#/components/schemas/Verdict"},"code":{"type":"string","description":"Stable machine identifier for this finding. Branch on this rather than on `detail`. See x-reason-codes for the current set, grouped by the verdict each carries."},"kind":{"type":"string","enum":["fact","heuristic"],"description":"fact is established; heuristic is inference and never convicts on its own."},"source":{"type":"string","description":"The upstream this reason came from."},"detail":{"type":"string"},"data":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_json","payment_identity_missing","free_quota_exhausted","not_found","method_not_allowed","payment_already_used","payment_claim_in_flight","invalid_request","unsupported_ecosystem","upstream_error","upstream_timeout"]},"message":{"type":"string","description":"Never names an upstream, an internal status, or the package."}}}}}},"securitySchemes":{"x402Payment":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"A signed x402 payment authorisation. Call without it to receive 402 and the terms in `accepts`, sign those terms, then resend. Scheme `exact` on algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=, $0.05 in USDC. One authorisation buys one verification; replaying it answers 409 without the result. One payer runs one verification at a time; a second in parallel answers 409 and stays unspent."}}}}