npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sanning/anchor-s3

v0.20.0

Published

Anchor-as-you-store for S3: wrap your S3 client so every putObject also sends a signed evidence envelope for the object to Sanning and writes the envelope and its record beside the object as a .provenance.json sidecar. Also the S3 destination for the SDK

Readme

@sanning/anchor-s3

Anchor the objects you already store in S3, and keep the bytes your evidence commits to in a bucket you own. Two jobs share this package because they share an S3 client.

npm install @sanning/anchor-s3 @sanning/anchor @aws-sdk/client-s3

Anchor as you store

Wrap your S3 client once, and every putObject also signs an evidence record of the exact bytes stored and writes that record beside the object:

import { S3Client } from "@aws-sdk/client-s3";
import { createAnchorer, LocalEd25519Signer, ObjectLogStore } from "@sanning/anchor";
import { envelopeAnchoredS3, S3ObjectStore } from "@sanning/anchor-s3";

const anchorer = createAnchorer({
  // Writes to a permanent public record. Use "dev" until you mean it.
  environment: "production",
  signer: LocalEd25519Signer.fromSeedHex(process.env.SANNING_SIGNING_SEED!),
  subject: { type: "agent", agent_id: "model-registry" },
  // The key needs `agent:enroll` and `anchor:write`.
  apiKey: process.env.SANNING_API_KEY!,
  // Required in production: the plane refuses an envelope that names no log
  // store (400 no-log-store), and a production record with no locator is
  // refused before it is signed. This is where the record the envelope commits to is kept.
  logStore: new ObjectLogStore(
    new S3ObjectStore({ bucket: "evidence-models", client: new S3Client({}) }),
  ),
});

const s3 = envelopeAnchoredS3(new S3Client({}), anchorer);

const { result, provenanceKey, location, ref } = await s3.putObject({
  Bucket: "models",
  Key: "prod/scorer.pkl",
  // Hashed in this process. These bytes go to your bucket, never to Sanning.
  Body: modelBytes,
});

result.eventId; // the id this process minted for the record
provenanceKey;  // "prod/scorer.pkl.provenance.json": verify offline, anytime
ref;            // "s3+opaque:<sha256>": the locator that went public
location;       // "s3://models/prod/scorer.pkl": stays with you

Each putObject sends one signed envelope to Sanning, and nothing comes back: no acknowledgement to keep and no transaction id. Sanning witnesses envelopes on an interval, and the proof travels in the pack you build at hand-over.

Body must be a string or a Uint8Array: it is hashed in-process, and streams are not accepted here.

Production refuses auto-generated secrets: createAnchorer throws unless you pass a signer and a subject. See @sanning/anchor.

[!NOTE] A logStore on the anchorer stores the object's bytes a second time. The sidecar holds the record, and the bucket already holds the object. A hand-over pack is built from a log store, so configure one when you need a pack, and expect the duplicate.

Two behaviours are worth knowing before you wire it in:

  • If anchoring fails, the object is already stored but no sidecar is written. The put itself is never rolled back.
  • The anchored locator defaults to opaque. { locator: "plaintext" } opts back into publishing bucket and key, and any other value throws at wrap time rather than disclosing by accident.

No closing record

Nothing envelopeAnchoredS3 anchors carries a langchain.run_closed / vercel_ai.run_closed-style event. This is a limit, not an omission: every other adapter (LangChain, Vercel) writes a closing record at the end of a run it can name (a root run, a chain key). This wrapper has no run at all. It never passes chain to anchorer.anchor(), so each putObject is its own independent GENESIS record: nothing on the wire ties two puts from one wrapper instance together. A closing record here would claim to close a run that does not exist on the wire, and a reader would have no way to tell that claim from a real one.

Whether this wrapper chains its own puts, which would give it a run for a closing record to live in, is an open question tracked in this project's issue tracker -- raised, not settled by this change.

The file role

putObject takes an optional second argument naming what the object IS, customer-supplied and carried verbatim into the committed record's metadata.file:

await s3.putObject(
  { Bucket: "claims", Key: "4471/policy.pdf", Body: policyBytes },
  { role: "input", source: "customer-portal-upload" },
);

await s3.putObject(
  { Bucket: "claims", Key: "4471/decision.pdf", Body: decisionBytes },
  { role: "output", destination: "customer-notification-queue" },
);

All three fields are optional and independent: name a role with no source, or a source with no role. Absent, never empty -- a put that names none of the three carries no metadata.file at all. source and destination are opaque strings this SDK never parses or validates; they sit at the same disclosure tier langchain.artifact's path already does: hashed and signed as part of the committed record, retained in your own log store, and disclosed only when you hand over a pack. Neither field ever reaches ref or payloadRef, the locator this README's own "Your bucket and key are not published" section describes -- putting a source or destination there would publish it forever, which this option is not for.

Your bucket and key are not published

The provenance record carries a payload locator, a pointer to where the anchored bytes live. That locator sits inside the signed scope (event.ref in the record), so whatever goes in it is permanent, public and un-redactable.

Bucket names and object keys routinely embed customer names, tenant ids, agent names and model names. So the default locator is opaque:

s3+opaque:<sha256 hex of "s3://<bucket>/<key>">

That is stable and correlatable, so the same object always yields the same locator and enumeration and reverse lookup still work. It is confirmable by anyone who already holds the path, and reveals nothing to anyone who does not. The real path is written to the sidecar as location, which lives in the same bucket as the object it describes, so it discloses nothing to its reader.

Confirm the binding with one line:

import { opaqueLocator } from "@sanning/anchor-s3";

(await opaqueLocator(sidecar.location)) === sidecar.ref; // true

Integrity does not depend on the locator. Per envelope-spec.md §2 a locator is an agent-asserted pointer, never a trust signal: a lying locator is caught by the hash, never trusted on its own. Verification binds on content_hash and payload_hash, which are unchanged.

Need the self-describing s3://bucket/key form? Ask for it explicitly, per wrapper:

const s3 = envelopeAnchoredS3(new S3Client({}), anchorer, { locator: "plaintext" });

That publishes the bucket and key permanently. It is the right choice when the path is already public, such as an open data bucket or a published model registry, and self-describing evidence is worth more than the disclosure.

Verify a sidecar

The sidecar is JSON: { eventId, envelope, record, contentHash, payloadHash, environment, location, ref, locatorMode }. Anyone holding the object and its sidecar verifies offline with the read-only @sanning/proof, with no Sanning service in the trust path:

import { ed25519Verify, jcs, sha256Hex, utf8 } from "@sanning/proof";

const sidecar = JSON.parse(sidecarJson);

// 1. The object bytes are what was anchored.
(await sha256Hex(objectBytes)) === sidecar.record.event.content_hash;

// 2. The record is what the envelope committed to.
(await sha256Hex(utf8(jcs(sidecar.record)))) === sidecar.envelope.payload_hash;

// 3. The envelope is authentically signed.
const { signature, ...pre } = sidecar.envelope;
await ed25519Verify(utf8(jcs(pre)), signature, sidecar.envelope.public_key);

Those three checks prove the bytes and the signature. They do not prove when Sanning witnessed the record: that proof is in the hand-over pack, which the bundle command builds from a log store (below).

Keep the bytes an event commits to

envelopeAnchoredS3 anchors objects you already store. S3ObjectStore runs the opposite direction: the anchor SDK hands it bytes it has just hashed, and it keeps them, so an event stays verifiable later and a pack can be built.

import { createAnchorer, ObjectLogStore } from "@sanning/anchor";
import { S3ObjectStore } from "@sanning/anchor-s3";
import { S3Client } from "@aws-sdk/client-s3";

const logStore = new ObjectLogStore(
  new S3ObjectStore({ bucket: "evidence-claims", client: new S3Client({}) }),
);

It takes your client, so any credential arrangement works. endpoint plus forcePathStyle (default true) make MinIO, R2, Backblaze and AWS behave identically. A client the store builds itself sends no Expect: 100-continue; a client you pass in keeps its own setting.

The on-disk layout is a versioned contract, specs/log-store.md, so anyone holding the bucket can resolve an event's bytes with no connector and no Sanning.

Bucket defaults: protected, or the SDK says why not

On first use the store checks the bucket, once, before it writes a byte. There are two acceptable outcomes and a third this exists to prevent.

const objects = new S3ObjectStore({
  bucket: "evidence-claims",
  storeProtection: "refuse",   // default "warn"
  createBucket: true,          // default true
  objectLock: { mode: "GOVERNANCE", days: 365 },
});
  • Absent creates the bucket with ObjectLockEnabledForBucket, versioning on, and a default retention rule. Nothing is printed; the happy path is not an incident.
  • A bucket that is there without Object Lock gives a named warning, and refuse stops the write. It is not repaired, because S3 only enables Object Lock at bucket creation, so a bucket that already exists cannot be upgraded. The message says to make a fresh one rather than sending you to a console page that cannot help.
  • A backend without Object Lock (some S3-compatible services are one) degrades with the reason named, never silently. Under refuse it creates nothing at all.
  • Could not check, such as a credential without s3:GetObjectLockConfiguration or a 403 on HeadBucket, is reported as unknown, and refuse treats that as a refusal. Unknown is not "off": a guard that stands down where it cannot look guards nothing.

Object Lock enabled is not the same as protected. With no default retention rule, objects in a lock-enabled bucket carry no retention and delete like any other, so that state is reported as unprotected, because it is. This adapter sends no per-object retention headers and relies on the bucket's default rule.

checkProtection() returns the verdict without gating, and names no bucket and no key, so it is safe to surface to something that must stay content-blind.

Full behaviour, the three IAM policies (provisioner, writer, reader), and the backend table: docs/log-store-bucket.md.

Build a pack straight from the bucket

The bundle command that assembles a hand-over pack takes either a local sanning.logstore/v1 store root, the directory holding content/ and records/, or an s3:// URL that resolves through this package. Reading a bucket needs SANNING_S3_ENDPOINT, SANNING_S3_ACCESS_KEY_ID and SANNING_S3_SECRET_ACCESS_KEY in the environment, with no flag for them, because a credential in argv lands in shell history.

A local copy still works, so syncing the prefix down first stays a valid route when you would rather hand the command a directory:

npx @sanning/anchor bundle \
  --agent claims-triage \
  --from 2026-06-01 --to 2026-06-30 \
  --logs ./logstore \
  --out claims-triage-2026-06.zip

License

MIT. @aws-sdk/client-s3 is a peer dependency; this package depends only on @sanning/anchor.