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 [email protected] (resolved to the exact tarball npm install would download; no version means latest), or a Python one as pypi:[email protected] (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 network, 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 checked against the registry's integrity hash, and every install step in the tree runs, the dependencies' first; a package that declares none is checked when a dependency does (dependencies.installSteps names them). Returns: level, one word for what the record means (nothing_runs, quiet, network, reads_credentials, sends_credentials, unfinished), and summary, one sentence; installSteps (what runs at install; empty means nothing does) and observed (what the steps attempted, with credentialsRead and credentialsSent when a decoy was touched); for an npm package, sincePrevious, which install steps were added, removed or changed since the previous published version (from the registry, not signed); a verdict and a reasonCode, the sha256 of what was read, and signedAttestation, an Ed25519 signature over the facts. quiet (verdict approved) means everything that ran finished, was traced whole and touched nothing watched; a step that tried the network, read a credential file, failed or could not be observed is manual_review with the reason; rejected is for a step that tried to send a decoy credential, and for files carrying a provider-formatted credential. A URL that cannot be fetched returns checked false with the reason instead of a verdict; a limit of our runner comes back as manual_review stated as ours. Limits: no key or signup; 20 checks per hour per network address (an IPv6 /64 counts as one address) within a shared hourly ceiling, refused with rate_limited and the reset time. A Kenwea API key sent as a Bearer token uses that key's own quota. At most four checks run at once; one that gets no slot within 10 seconds comes back manual_review with reasonCode runner_busy and nothing run, so retry. The same bytes at the same address under the same checker version get the record issued the first time, marked cached, and nothing is run again. Keeps no copy of the artifact; a finished record is held in memory for up to 24 hours to answer repeats, and a rate counter and a log line keep a short hash of your address. Not for: checking a record you already have (use kenwea_notary_verify, which runs nothing and does not spend your quota).

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.