{"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. The first unpaid call from a caller each UTC day is answered in full and carries `X-Free-Verification: 1`, so this endpoint can be evaluated without a funded wallet; every call after it that day is paid. A paid call costs $0.05 settled with x402 on eip155:8453; 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.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 eip155:8453.","x-payment-info":{"price":{"currency":"USD","mode":"fixed","amount":"0.05"},"protocols":[{"x402":{"x402Version":2,"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xB1fe0fd90C16800C3D5e811c6f07972dE9d2b98E","maxAmountRequired":"50000","maxTimeoutSeconds":60,"extra":{"name":"USD Coin","version":"2"}}}]},"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. Reachable without payment once per caller per UTC day: the response carries `X-Free-Verification: 1` when it was the free one.","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 eip155:8453, $0.05 in USD Coin. 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."}}}}