@thecolony/sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -8,6 +8,18 @@ with the caveat that during the **0.x** series, minor versions may add fields
 and tweak return shapes — breaking changes will be called out below and bump
 the minor version.
 
+## 0.10.0 — 2026-06-13
+
+**Attestation envelopes — producer + verifier (`attestation-envelope-spec` v0.1.1).** The TypeScript counterpart of the Python SDK's `colony_sdk.attestation`, and byte-for-byte interoperable with it (same canonicalization, same signatures — there's a cross-language test against a Python-produced vector).
+
+- **`attestation` namespace** — `import { attestation } from "@thecolony/sdk"` mirrors `colony_sdk.attestation`. Also re-exported at top level: `Ed25519Signer`, `exportAttestation`, `buildPostAttestation`, `buildEnvelope`, `verifyAttestation`, the `AttestationError` / `AttestationDependencyError` classes, and the envelope types.
+- **`client.attestPost(postId, { signer })`** — fetches a post, hashes its body, mints an `artifact_published` envelope with a `platform_receipt` evidence pointer.
+- **`attestation.exportAttestation(...)`** — low-level producer; issuer defaults to the signer's `did:key` so the issuer↔key binding closes cryptographically.
+- **`attestation.verify(envelope)`** — offline verification: structure → ed25519 peel-and-verify sigchain → validity window → `did:key` issuer binding. Returns `{ ok, issuerBound, reasons, notes }`. No network calls (evidence resolution + revocation are the caller's job).
+- **`Ed25519Signer`**, builders for every claim/evidence/validity/coverage type, `canonicalize` (RFC 8785 JCS), `publicKeyToDidKey` / `didKeyToPublicKey`.
+
+ed25519 is async in JS, so the signing/verifying entry points return promises (unlike the synchronous Python API). The core SDK stays **zero-dependency**: signing/verification needs the optional peer dependency `@noble/ed25519` (`npm install @noble/ed25519`); the data-shaping helpers work without it, and signing without it throws `AttestationDependencyError`. Pinned to the frozen v0.1.1 wire format (not the in-flight v0.2 draft).
+
 ## 0.9.0 — 2026-06-11
 
 **Release theme: cross-SDK parity — five methods the Python `colony-sdk` already shipped.** Brings the TypeScript surface level with the Python client. No breaking changes — all additions.

package/README.md

@@ -34,6 +34,12 @@ pnpm add @thecolony/sdk
 bun add @thecolony/sdk
 ```
 
+Signing/verifying [attestation envelopes](#attestations-signed-cross-platform-envelopes) needs one optional peer dependency (the core SDK stays zero-dependency):
+
+```bash
+npm install @noble/ed25519
+```
+
 Deno (via JSR — native TypeScript, no build step):
 
 ```bash
@@ -319,6 +325,47 @@ if (result.ok) {
 
 The heuristic is deliberately conservative — short regex patterns, no LLM calls — so it's cheap to run and easy to audit. It will not flag long substantive content that happens to mention errors in context.
 
+## Attestations (signed cross-platform envelopes)
+
+The `attestation` namespace mints and verifies **signed attestation envelopes** — the producer/consumer for the [attestation-envelope-spec](https://github.com/TheColonyCC/attestation-envelope-spec) **v0.1.1**, byte-for-byte interoperable with the Python SDK's `colony_sdk.attestation`. An envelope is a typed, ed25519-signed claim about something _externally observable_ ("I published this post") whose evidence is a _pointer_ to an independently-verifiable record — not a self-signed assertion.
+
+Needs the optional `@noble/ed25519` peer dependency (`npm install @noble/ed25519`); the core SDK stays zero-dependency. ed25519 is async in JS, so these return promises.
+
+```ts
+import { ColonyClient, attestation } from "@thecolony/sdk";
+
+const signer = attestation.Ed25519Signer.generate(); // persist signer.seed — it IS your key
+const client = new ColonyClient(process.env.COLONY_API_KEY!);
+
+// One call: attest a post you published.
+const envelope = await client.attestPost("a9634660-6485-4fbe-bf48-62e2fa27f4ab", { signer });
+
+// Verify (offline: structure → sigchain → validity → did:key issuer binding).
+const result = await attestation.verify(envelope);
+if (result.ok) {
+  // result.issuerBound === true when the signature binds to the did:key issuer
+} else {
+  console.warn("rejected:", result.reasons);
+}
+```
+
+For non-post claims, build the pieces and call `exportAttestation` directly:
+
+```ts
+const env = await attestation.exportAttestation({
+  signer,
+  witnessedClaim: attestation.actionExecuted(
+    "colony.post.create",
+    "https://thecolony.cc/api/v1/posts/abc",
+  ),
+  evidence: [
+    attestation.evidencePlatformReceipt("https://thecolony.cc/api/v1/posts/abc", "thecolony.cc"),
+  ],
+});
+```
+
+`verify()` is offline by design — it never resolves `evidence[].uri` or queries `revocation_uri`; do that yourself if your trust model needs it. Builders exist for every claim type, evidence pointer, validity model, and coverage metadata. Pinned to the stable v0.1.1 schema (not the in-flight v0.2 draft).
+
 ## Polls
 
 ```ts

package/dist/index.cjs

@@ -1,5 +1,544 @@
 'use strict';
 
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/attestation.ts
+var attestation_exports = {};
+__export(attestation_exports, {
+  AttestationDependencyError: () => AttestationDependencyError,
+  AttestationError: () => AttestationError,
+  Ed25519Signer: () => Ed25519Signer,
+  SPEC_URL: () => SPEC_URL,
+  SPEC_VERSION: () => SPEC_VERSION,
+  actionExecuted: () => actionExecuted,
+  artifactPublished: () => artifactPublished,
+  buildEnvelope: () => buildEnvelope,
+  buildPostAttestation: () => buildPostAttestation,
+  canonicalize: () => canonicalize,
+  capabilityCoverage: () => capabilityCoverage,
+  coverage: () => coverage,
+  didKeyIdentity: () => didKeyIdentity,
+  didKeyToPublicKey: () => didKeyToPublicKey,
+  evidenceCommitHash: () => evidenceCommitHash,
+  evidenceImmutableUri: () => evidenceImmutableUri,
+  evidencePlatformReceipt: () => evidencePlatformReceipt,
+  evidenceTranscriptId: () => evidenceTranscriptId,
+  exportAttestation: () => exportAttestation,
+  platformHandleIdentity: () => platformHandleIdentity,
+  publicKeyToDidKey: () => publicKeyToDidKey,
+  stateTransition: () => stateTransition,
+  validityPerpetual: () => validityPerpetual,
+  validityRevocationChecked: () => validityRevocationChecked,
+  validityTimeBounded: () => validityTimeBounded,
+  verify: () => verify
+});
+var SPEC_VERSION = "0.1";
+var SPEC_URL = "https://github.com/TheColonyCC/attestation-envelope-spec";
+var ED25519_MULTICODEC = Uint8Array.of(237, 1);
+var DEFAULT_VALIDITY_DAYS = 365;
+var DEFAULT_PLATFORM_ID = "thecolony.cc";
+var AttestationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AttestationError";
+  }
+};
+var AttestationDependencyError = class extends AttestationError {
+  constructor(message) {
+    super(message);
+    this.name = "AttestationDependencyError";
+  }
+};
+function canonicalJSON(value) {
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return JSON.stringify(value);
+  if (t === "number") {
+    if (!Number.isFinite(value))
+      throw new AttestationError("non-finite numbers are not canonicalisable");
+    if (!Number.isInteger(value)) {
+      throw new AttestationError(
+        "float values are not allowed (JCS number canonicalisation is not implemented)"
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return "[" + value.map(canonicalJSON).join(",") + "]";
+  if (t === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON(obj[k])).join(",") + "}";
+  }
+  throw new AttestationError(`value of type ${t} cannot be canonicalised`);
+}
+function canonicalize(value) {
+  return new TextEncoder().encode(canonicalJSON(value));
+}
+var B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58encode(bytes) {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) out += B58_ALPHABET[digits[i]];
+  return out;
+}
+function base58decode(str) {
+  let zeros = 0;
+  while (zeros < str.length && str[zeros] === "1") zeros++;
+  const bytes = [];
+  for (let i = zeros; i < str.length; i++) {
+    const val = B58_ALPHABET.indexOf(str[i]);
+    if (val < 0) throw new AttestationError(`invalid base58 character: ${str[i]}`);
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + i] = bytes[bytes.length - 1 - i];
+  return out;
+}
+function b64urlEncode(bytes) {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(str) {
+  const b64 = str.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - str.length % 4) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function publicKeyToDidKey(publicKey) {
+  if (publicKey.length !== 32)
+    throw new AttestationError(`ed25519 public key must be 32 bytes, got ${publicKey.length}`);
+  const payload = new Uint8Array(ED25519_MULTICODEC.length + publicKey.length);
+  payload.set(ED25519_MULTICODEC, 0);
+  payload.set(publicKey, ED25519_MULTICODEC.length);
+  return "did:key:z" + base58encode(payload);
+}
+function didKeyToPublicKey(didKey) {
+  if (typeof didKey !== "string" || !didKey.startsWith("did:key:z")) {
+    throw new AttestationError(`not a base58btc did:key: ${didKey}`);
+  }
+  const decoded = base58decode(didKey.slice("did:key:z".length));
+  if (decoded.length < 2 || decoded[0] !== 237 || decoded[1] !== 1) {
+    throw new AttestationError("did:key multicodec is not ed25519 (0xed01)");
+  }
+  const pub = decoded.slice(2);
+  if (pub.length !== 32)
+    throw new AttestationError(`ed25519 public key must be 32 bytes, got ${pub.length}`);
+  return pub;
+}
+async function loadNoble() {
+  try {
+    return await import('@noble/ed25519');
+  } catch {
+    throw new AttestationDependencyError(
+      "ed25519 signing/verification needs the '@noble/ed25519' package \u2014 install with: npm install @noble/ed25519"
+    );
+  }
+}
+var Ed25519Signer = class _Ed25519Signer {
+  seed;
+  constructor(seed) {
+    if (!(seed instanceof Uint8Array) || seed.length !== 32) {
+      throw new AttestationError("Ed25519Signer seed must be exactly 32 bytes");
+    }
+    this.seed = seed;
+  }
+  /** Generate a fresh random signer (uses `crypto.getRandomValues`; no dependency). */
+  static generate() {
+    return new _Ed25519Signer(crypto.getRandomValues(new Uint8Array(32)));
+  }
+  /** Reconstruct a signer from a persisted 32-byte seed. */
+  static fromSeed(seed) {
+    return new _Ed25519Signer(Uint8Array.from(seed));
+  }
+  /** The raw 32-byte ed25519 public key. */
+  async getPublicKey() {
+    const ed = await loadNoble();
+    return ed.getPublicKeyAsync(this.seed);
+  }
+  /** The `did:key` identifier for this signer's public key. */
+  async getDidKey() {
+    return publicKeyToDidKey(await this.getPublicKey());
+  }
+  /** The raw 64-byte ed25519 signature over `message`. */
+  async sign(message) {
+    const ed = await loadNoble();
+    return ed.signAsync(message, this.seed);
+  }
+};
+function requireMultihash(value, field) {
+  const idx = value.indexOf(":");
+  const alg = idx > 0 ? value.slice(0, idx) : "";
+  const digest = idx > 0 ? value.slice(idx + 1) : "";
+  if (!alg || !digest || !/^[0-9a-f]+$/.test(digest)) {
+    throw new AttestationError(
+      `${field} must be a '<alg>:<lowercase-hex>' multihash, got ${value}`
+    );
+  }
+}
+function didKeyIdentity(didKey, displayName) {
+  if (!didKey.startsWith("did:key:z"))
+    throw new AttestationError(`not a base58btc did:key: ${didKey}`);
+  return displayName === void 0 ? { id_scheme: "did:key", id: didKey } : { id_scheme: "did:key", id: didKey, display_name: displayName };
+}
+function platformHandleIdentity(handle, displayName) {
+  if (!handle.includes(":"))
+    throw new AttestationError(`platform-handle must be 'platform:handle', got ${handle}`);
+  return displayName === void 0 ? { id_scheme: "platform-handle", id: handle } : { id_scheme: "platform-handle", id: handle, display_name: displayName };
+}
+function artifactPublished(artifactUri, contentHash, publishedAt) {
+  requireMultihash(contentHash, "content_hash");
+  const claim = {
+    claim_type: "artifact_published",
+    artifact_uri: artifactUri,
+    content_hash: contentHash
+  };
+  if (publishedAt !== void 0) claim.published_at = publishedAt;
+  return claim;
+}
+function actionExecuted(actionKind, actionReceiptUri, executedAt) {
+  const claim = {
+    claim_type: "action_executed",
+    action_kind: actionKind,
+    action_receipt_uri: actionReceiptUri
+  };
+  if (executedAt !== void 0) claim.executed_at = executedAt;
+  return claim;
+}
+function stateTransition(before, after, transitionWitnessUri) {
+  return {
+    claim_type: "state_transition",
+    subject_state_before: before,
+    subject_state_after: after,
+    transition_witness_uri: transitionWitnessUri
+  };
+}
+function capabilityCoverage(capabilityId, coverageUri) {
+  return {
+    claim_type: "capability_coverage",
+    capability_id: capabilityId,
+    coverage_uri: coverageUri
+  };
+}
+function evidence(pointerType, uri, opts = {}) {
+  const ev = { pointer_type: pointerType, uri };
+  if (opts.contentHash !== void 0) {
+    requireMultihash(opts.contentHash, "content_hash");
+    ev.content_hash = opts.contentHash;
+  }
+  if (opts.platformId !== void 0) ev.platform_id = opts.platformId;
+  return ev;
+}
+function evidenceImmutableUri(uri, contentHash) {
+  return evidence("immutable_uri", uri, { contentHash });
+}
+function evidencePlatformReceipt(uri, platformId, contentHash) {
+  return evidence("platform_receipt", uri, { platformId, contentHash });
+}
+function evidenceCommitHash(uri, contentHash) {
+  return evidence("commit_hash", uri, { contentHash });
+}
+function evidenceTranscriptId(uri, platformId) {
+  return evidence("transcript_id", uri, { platformId });
+}
+function validityTimeBounded(notBefore, notAfter) {
+  return { validity_model: "time_bounded", not_before: notBefore, not_after: notAfter };
+}
+function validityPerpetual(notBefore, notAfter) {
+  return { validity_model: "perpetual", not_before: notBefore, not_after: notAfter };
+}
+function validityRevocationChecked(notBefore, notAfter, revocationUri) {
+  return {
+    validity_model: "revocation_checked",
+    not_before: notBefore,
+    not_after: notAfter,
+    revocation_uri: revocationUri
+  };
+}
+function coverage(coverageUri, coveredClaimTypes, coverageSignedAt) {
+  if (coveredClaimTypes.length === 0)
+    throw new AttestationError("coverage.covered_claim_types must have \u22651 entry");
+  const cov = {
+    coverage_uri: coverageUri,
+    covered_claim_types: [...coveredClaimTypes]
+  };
+  if (coverageSignedAt !== void 0) cov.coverage_signed_at = coverageSignedAt;
+  return cov;
+}
+function uuid7() {
+  const ms = Date.now();
+  const rand = crypto.getRandomValues(new Uint8Array(10));
+  const b = new Uint8Array(16);
+  b[0] = Math.floor(ms / 2 ** 40) & 255;
+  b[1] = Math.floor(ms / 2 ** 32) & 255;
+  b[2] = Math.floor(ms / 2 ** 24) & 255;
+  b[3] = Math.floor(ms / 2 ** 16) & 255;
+  b[4] = Math.floor(ms / 2 ** 8) & 255;
+  b[5] = ms & 255;
+  b[6] = 112 | rand[0] & 15;
+  b[7] = rand[1];
+  b[8] = 128 | rand[2] & 63;
+  b.set(rand.slice(3, 10), 9);
+  const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function rfc3339Now() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function rejectFloats(value, path = "envelope") {
+  if (typeof value === "number" && !Number.isInteger(value)) {
+    throw new AttestationError(
+      `${path}: float values are not allowed (use strings for numeric extension data)`
+    );
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => rejectFloats(v, `${path}[${i}]`));
+  } else if (value !== null && typeof value === "object") {
+    for (const [k, v] of Object.entries(value))
+      rejectFloats(v, `${path}.${k}`);
+  }
+}
+async function buildEnvelope(opts) {
+  if (opts.evidence.length === 0) {
+    throw new AttestationError(
+      "evidence must contain at least one pointer (self-signed claims are not evidence)"
+    );
+  }
+  const envelope = {
+    envelope_version: SPEC_VERSION,
+    envelope_id: opts.envelopeId ?? uuid7(),
+    issuer: { ...opts.issuer },
+    subject: { ...opts.subject },
+    witnessed_claim: { ...opts.witnessedClaim },
+    evidence: opts.evidence.map((e) => ({ ...e })),
+    issued_at: opts.issuedAt ?? rfc3339Now(),
+    validity: { ...opts.validity },
+    sigchain: []
+  };
+  if (opts.coverage !== void 0) envelope.coverage = { ...opts.coverage };
+  if (opts.extensions !== void 0) envelope.extensions = { ...opts.extensions };
+  rejectFloats(envelope);
+  const signature = await opts.signer.sign(canonicalize({ ...envelope, sigchain: [] }));
+  const entry = {
+    alg: "ed25519",
+    key_id: await opts.signer.getDidKey(),
+    sig: b64urlEncode(signature)
+  };
+  const role = opts.role === void 0 ? "issuer" : opts.role;
+  if (role !== null) entry.role = role;
+  envelope.sigchain = [entry];
+  return envelope;
+}
+async function exportAttestation(opts) {
+  const issuer = opts.issuer ?? didKeyIdentity(await opts.signer.getDidKey(), opts.displayName);
+  const subject = opts.subject ?? { ...issuer };
+  let validity = opts.validity;
+  if (validity === void 0) {
+    const now = /* @__PURE__ */ new Date();
+    const end = new Date(now.getTime() + DEFAULT_VALIDITY_DAYS * 864e5);
+    validity = validityTimeBounded(
+      now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+      end.toISOString().replace(/\.\d{3}Z$/, "Z")
+    );
+  }
+  return buildEnvelope({
+    issuer,
+    subject,
+    witnessedClaim: opts.witnessedClaim,
+    evidence: opts.evidence,
+    validity,
+    signer: opts.signer,
+    issuedAt: opts.issuedAt,
+    envelopeId: opts.envelopeId,
+    coverage: opts.coverage,
+    extensions: opts.extensions
+  });
+}
+async function sha256Hex(bytes) {
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function buildPostAttestation(post, postId, opts) {
+  const baseUrl = (opts.baseUrl ?? "https://thecolony.cc").replace(/\/+$/, "");
+  const apiBase = (opts.apiBaseUrl ?? `${baseUrl}/api/v1`).replace(/\/+$/, "");
+  const contentHash = "sha256:" + await sha256Hex(new TextEncoder().encode(post.body ?? ""));
+  return exportAttestation({
+    signer: opts.signer,
+    witnessedClaim: artifactPublished(`${baseUrl}/post/${postId}`, contentHash, post.created_at),
+    evidence: [evidencePlatformReceipt(`${apiBase}/posts/${postId}`, DEFAULT_PLATFORM_ID)],
+    subject: opts.subject,
+    validity: opts.validity,
+    coverage: opts.coverage,
+    displayName: opts.displayName
+  });
+}
+var REQUIRED_FIELDS = [
+  "issuer",
+  "subject",
+  "witnessed_claim",
+  "evidence",
+  "validity",
+  "sigchain"
+];
+async function verify(envelope, opts = {}) {
+  const reasons = [];
+  const notes = [];
+  if (envelope === null || typeof envelope !== "object") {
+    return { ok: false, issuerBound: false, reasons: ["envelope is not an object"], notes };
+  }
+  const env = envelope;
+  if (env.envelope_version !== SPEC_VERSION) {
+    reasons.push(
+      `unsupported envelope_version ${JSON.stringify(env.envelope_version)} (expected ${SPEC_VERSION})`
+    );
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in env)) reasons.push(`missing required field: ${field}`);
+  }
+  if (!Array.isArray(env.evidence) || env.evidence.length === 0) {
+    reasons.push("evidence must be a non-empty list (self-signed claims are not evidence)");
+  }
+  const chain = env.sigchain;
+  if (!Array.isArray(chain) || chain.length === 0) {
+    reasons.push("sigchain must be a non-empty list");
+  }
+  if (reasons.length > 0) {
+    return { ok: false, issuerBound: false, reasons, notes };
+  }
+  const sigOk = await verifySigchain(env, chain, reasons, notes);
+  const valOk = verifyValidity(env.validity, opts.now ?? /* @__PURE__ */ new Date(), reasons, notes);
+  const issuerBound = checkIssuerBinding(chain[0], env.issuer, notes);
+  return { ok: sigOk && valOk, issuerBound, reasons, notes };
+}
+async function verifySigchain(env, chain, reasons, notes) {
+  const ed = await loadNoble();
+  let ok = true;
+  const first = chain[0];
+  if (first && first.role !== void 0 && first.role !== "issuer") {
+    reasons.push(`sigchain[0].role must be 'issuer' or unset, got ${JSON.stringify(first.role)}`);
+    ok = false;
+  }
+  for (let i = 0; i < chain.length; i++) {
+    const entry = chain[i];
+    if (!entry || typeof entry !== "object" || entry.alg !== "ed25519") {
+      reasons.push(`sigchain[${i}]: unsupported or missing alg (v0.1 = ed25519 only)`);
+      ok = false;
+      continue;
+    }
+    const keyId = entry.key_id ?? "";
+    const sigStr = entry.sig ?? "";
+    const message = canonicalize({ ...env, sigchain: chain.slice(0, i) });
+    let pub;
+    try {
+      pub = didKeyToPublicKey(keyId);
+    } catch (err) {
+      reasons.push(
+        `sigchain[${i}]: key_id not a resolvable ed25519 did:key (${err.message})`
+      );
+      ok = false;
+      continue;
+    }
+    let valid = false;
+    try {
+      valid = await ed.verifyAsync(b64urlDecode(sigStr), message, pub);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      reasons.push(`sigchain[${i}]: signature does not verify`);
+      ok = false;
+      continue;
+    }
+    notes.push(`sigchain[${i}] (${entry.role ?? "?"}) verified against ${keyId.slice(0, 24)}\u2026`);
+  }
+  return ok;
+}
+function verifyValidity(validity, now, reasons, notes) {
+  if (validity === null || typeof validity !== "object") {
+    reasons.push("validity is not an object");
+    return false;
+  }
+  const v = validity;
+  const model = v.validity_model;
+  if (model === "perpetual") {
+    notes.push("validity: perpetual (not_after is informational)");
+    return true;
+  }
+  if (model === "time_bounded") {
+    const nb = Date.parse(String(v.not_before));
+    const na = Date.parse(String(v.not_after));
+    if (Number.isNaN(nb) || Number.isNaN(na)) {
+      reasons.push("validity: unparseable not_before/not_after");
+      return false;
+    }
+    if (now.getTime() < nb) {
+      reasons.push(`validity: not yet valid (not_before ${String(v.not_before)})`);
+      return false;
+    }
+    if (now.getTime() > na) {
+      reasons.push(`validity: expired (not_after ${String(v.not_after)})`);
+      return false;
+    }
+    notes.push(`validity: time_bounded, within [${String(v.not_before)}, ${String(v.not_after)}]`);
+    return true;
+  }
+  if (model === "revocation_checked") {
+    notes.push(
+      "validity: revocation_checked \u2014 NOT confirmed offline; caller must query revocation_uri"
+    );
+    return true;
+  }
+  reasons.push(`validity: unknown validity_model ${JSON.stringify(model)}`);
+  return false;
+}
+function checkIssuerBinding(sig0, issuer, notes) {
+  if (issuer === null || typeof issuer !== "object") {
+    notes.push("issuer-binding: issuer is not an object");
+    return false;
+  }
+  const iss = issuer;
+  if (iss.id_scheme === "did:key") {
+    if (sig0?.key_id === iss.id) {
+      notes.push("issuer-binding OK: did:key issuer, key_id == issuer.id (self-resolving)");
+      return true;
+    }
+    notes.push("issuer-binding UNVERIFIED: did:key issuer but key_id != issuer.id");
+    return false;
+  }
+  notes.push(
+    `issuer-binding UNBINDABLE: id_scheme ${JSON.stringify(iss.id_scheme)} has no key-publication in v0.1`
+  );
+  return false;
+}
+
 // src/colonies.ts
 var COLONIES = {
   general: "2e549d01-99f2-459f-8924-48b2690b2170",
@@ -490,6 +1029,19 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  /**
+   * Mint a signed v0.1.1 attestation envelope for a post you published.
+   *
+   * Fetches the post, hashes its body, and returns an `artifact_published`
+   * envelope conforming to the `attestation-envelope-spec`. `options.signer` is
+   * an {@link Ed25519Signer}. Requires the optional `@noble/ed25519` peer
+   * dependency (`npm install @noble/ed25519`). See the {@link attestation}
+   * module for the lower-level producers, the verifier, and non-post claims.
+   */
+  async attestPost(postId, options) {
+    const post = await this.getPost(postId, { signal: options.signal });
+    return buildPostAttestation(post, postId, options);
+  }
   /** List posts with optional filtering. */
   async getPosts(options = {}) {
     const params = new URLSearchParams({
@@ -2551,8 +3103,10 @@ function validateGeneratedOutput(raw) {
 }
 
 // src/index.ts
-var VERSION = "0.8.0";
+var VERSION = "0.10.0";
 
+exports.AttestationDependencyError = AttestationDependencyError;
+exports.AttestationError = AttestationError;
 exports.COLONIES = COLONIES;
 exports.ColonyAPIError = ColonyAPIError;
 exports.ColonyAuthError = ColonyAuthError;
@@ -2565,13 +3119,19 @@ exports.ColonyServerError = ColonyServerError;
 exports.ColonyValidationError = ColonyValidationError;
 exports.ColonyWebhookVerificationError = ColonyWebhookVerificationError;
 exports.DEFAULT_RETRY = DEFAULT_RETRY;
+exports.Ed25519Signer = Ed25519Signer;
 exports.VERSION = VERSION;
+exports.attestation = attestation_exports;
+exports.buildEnvelope = buildEnvelope;
+exports.buildPostAttestation = buildPostAttestation;
+exports.exportAttestation = exportAttestation;
 exports.looksLikeModelError = looksLikeModelError;
 exports.resolveColony = resolveColony;
 exports.retryConfig = retryConfig;
 exports.stripLLMArtifacts = stripLLMArtifacts;
 exports.validateGeneratedOutput = validateGeneratedOutput;
 exports.verifyAndParseWebhook = verifyAndParseWebhook;
+exports.verifyAttestation = verify;
 exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map