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). Behavior: Kenwea downloads the bytes (up to 10 MiB) and runs executable content in isolation: no network, all capabilities dropped, read-only filesystem, 15 seconds for a file and 45 for a package. Returns: a verdict (approved, manual_review or rejected), the sha256 of what was read, and signedAttestation, an Ed25519 signature over those facts. 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 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. Stores nothing about the artifact or what you asked; only a rate counter and a log line with 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).

{'type': 'object', 'properties': {'package': {'type': 'string', 'description': 'npm package name with an optional version or dist-tag, for example express, express@4.18.2 or @types/node@20.0.0. Omit when using artifactRef.'}, 'artifactRef': {'type': 'string', 'format': 'uri', 'description': 'Public https URL of the artifact: a single .js, .mjs, .cjs or .py file, a shebang script, an npm tarball (.tgz) or a Python wheel or zip. Omit when using package.'}}}

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 the key from https://www.kenwea.com/.well-known/kenwea-attestation-key, the address every signed record names, and caches it for an hour. Runs nothing, read-only, never counts against the check quota. Fails with key_unavailable if the key cannot be fetched. Returns: keyId (compare it with a record's signedAttestation.keyId), algorithm ed25519, the key as base64 (32 raw bytes) and as PEM, and keyUrl. To verify, check signedAttestation.signature (base64) over the exact bytes of signedAttestation.payload with this key. Not for: checking an artifact (use kenwea.notary.check) or having the check done for you (use kenwea.notary.verify).

{'type': 'object', 'properties': {}}

Check a signed record produced by kenwea.notary.check: whether its signature is valid under Kenwea's published Ed25519 key, and what it attests. 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 the public key, which it caches for an hour. It checks against the key published now, so a record signed before a key rotation returns valid false; compare the returned keyId with the record's keyId to tell that apart from tampering. Read-only and idempotent; it never counts against the check quota. Returns: valid, the keyId, and the signed facts (artifactRef, contentSha256, verdict, ran, exitCode, issuedAt); with contentSha256, also matchesContentSha256. An altered or re-serialised record returns valid false with the reason, not an error. If the key 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.getPublicKey and use any Ed25519 library.

{'type': 'object', 'required': ['payload', 'signature'], 'properties': {'payload': {'type': 'string', 'description': 'signedAttestation.payload from a check result, byte for byte.'}, 'signature': {'type': 'string', 'description': 'signedAttestation.signature, base64.'}, 'contentSha256': {'type': 'string', 'description': 'Optional sha256 (hex) of the bytes you hold; the answer then says whether the record is about them.'}}}