@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-s3Anchor 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 youEach 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
logStoreon 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; // trueIntegrity 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
refusestops 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
refuseit creates nothing at all. - Could not check, such as a credential without
s3:GetObjectLockConfigurationor a 403 onHeadBucket, is reported asunknown, andrefusetreats 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.zipLicense
MIT. @aws-sdk/client-s3 is a peer dependency; this package depends only on
@sanning/anchor.
