Kenwea Notary

Notarize what a file or npm package does at the moment Kenwea fetches it, and get a signed record anyone can check. Input: exactly one of artifactRef, a public https URL of a single file, npm tarball or Python wheel, or package, an npm package name such as express@4.18.2 (resolved to the exact tarball npm install would download; no version means latest), or a Python one as pypi:requests@2.31.0 (resolved on PyPI to the wheel this sandbox can import: pure Python, or musllinux for CPython 3.12). Behavior: Kenwea downloads the bytes (up to 32 MiB) and runs executable content in isolation: no route out (a stand-in network inside the sandbox answers lookups and connections on ports 80, 443, 8080 and 8443 and records them), all capabilities dropped, read-only filesystem, not as root, 15 seconds for a file and 55 for a package. For a package it runs the install steps npm would run (preinstall, install, postinstall, and the node-gyp step npm adds for a binding.gyp) with decoy credentials where a developer machine or CI runner keeps real ones (an npm token in ~/.npmrc and NPM_TOKEN, a GitHub token, AWS keys, an SSH key, CI variables), each traced for the network connections, DNS lookups and programs it attempts, the credential files it opens and any decoy it puts into what it sends or starts; a single file and a Python package run with the same decoys (plus a PyPI token for Python) and are traced the same way; a PyPI wheel (package pypi:name) is imported with its dependencies installed, resolved as pip would for CPython 3.12 on Linux x86_64 and each checked against PyPI's sha256. After its install a registry npm package is also loaded once, as an application would require or import it, and onLoad says what loading it did; a load that reaches the network or a credential is its own finding (load_tried_network, load_read_credentials, load_sent_credentials). For a registry package that runs something at install, the dependency tree npm would install goes in first, each tarball c…

Answer for every package in a project's npm dependency tree at once, from records the notary already holds. Input: lockfile, the text of a package-lock.json (lockfileVersion 2 or 3, or its JSON), a pnpm-lock.yaml (v5, v6, v9) or a yarn.lock (v1 or berry); or packages, a list of {name, version, hasInstallScript}. Behavior: the lockfile says which packages run something at install (hasInstallScript, or requiresBuild in pnpm up to v6), and where it does not (pnpm v9, yarn) the registry is asked for each version (usually a few percent run something); the rest run nothing of their own and are only counted. Each package that runs something is answered from its stored signed record, made by kenwea_notary_check's sandbox run with decoy credentials; one that has none yet is queued and checked in the background, about two a minute, so ask again later with the same tree to collect it. Nothing runs during the call and it does not spend the per-address check quota (60 tree calls an hour per address). Returns: summary, counts (total, runNothing, runSomething, answered, queued), findings (packages whose level is network, reads_credentials or sends_credentials), and packages, each with status (answered, queued, not_queued) and, when answered, level, summary, verdict, reasonCode, observed and signedAttestation. Verify each record with kenwea_notary_verify or your own Ed25519 code; the tree summary itself is not signed. Not for: one package you want checked now (use kenwea_notary_check). A lockfileVersion 1 file has no hasInstallScript flags and is refused with a reason.

Return Kenwea's published Ed25519 notary key, so a signed record can be verified with your own code instead of kenwea_notary_verify. Input: none. Behavior: reads Kenwea's published key list (https://www.kenwea.com/.well-known/kenwea-attestation-keys.json) and caches it for an hour. Runs nothing, read-only, never counts against the check quota. Fails with key_unavailable if the list cannot be fetched. Returns: the active key's keyId, algorithm ed25519, the key as base64 (32 raw bytes) and as PEM, keyUrl and keysUrl, and keys, every published key with its status (active, retired or revoked). To verify, check signedAttestation.signature (base64) over the exact bytes of signedAttestation.payload with the key whose keyId the payload names, and treat a revoked key as no signature. Not for: checking an artifact (use kenwea_notary_check) or having the check done for you (use kenwea_notary_verify).

Check a signed record produced by kenwea_notary_check: whether its signature is valid under Kenwea's published Ed25519 key, what it attests, and whether it is in Kenwea's public transparency log (log.included, proven with an inclusion proof against a checkpoint signed by the same key), so it was shown to everyone and not only to you. Input: payload and signature exactly as they appear in the record's signedAttestation. payload is a JSON string and must be passed byte for byte; re-serialising it (reordering keys, changing spacing) breaks the signature. signature is standard base64 with padding. Optionally contentSha256, the hex sha256 of bytes you hold, compared without regard to letter case. Behavior: runs nothing and makes no request except fetching Kenwea's published key list (https://www.kenwea.com/.well-known/kenwea-attestation-keys.json), which it caches for an hour and reads again when a record names a key it does not hold. A record names its key inside the signed payload (format 2) and is checked against that key; an older record is tried against every published key. A record signed with a key Kenwea has revoked returns valid false and says so. Read-only and idempotent; it never counts against the check quota. Returns: valid, the keyId and its status, and the signed facts (verdict, reasonCode, installSteps, observed, contentSha256, issuedAt and the rest); with contentSha256, also matchesContentSha256. An altered or re-serialised record returns valid false with the reason, not an error. If the key list cannot be fetched the call fails with key_unavailable and says why. Not for: learning what an artifact does (use kenwea_notary_check). To verify without this tool, take the key from kenwea_notary_get_public_key and use any Ed25519 library.