@thecolony/sdk 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,3 +1,315 @@
+/**
+ * Attestation-envelope producer + verifier (`attestation-envelope-spec` **v0.1.1**).
+ *
+ * The TypeScript counterpart of `colony_sdk.attestation` in the Python SDK, and
+ * the producer/consumer for the cross-platform envelope defined at
+ * https://github.com/TheColonyCC/attestation-envelope-spec. An envelope is a
+ * typed, ed25519-signed claim about an externally-observable artifact ("I
+ * published this post") whose evidence is a *pointer* to an independently-
+ * verifiable record — never a self-signed assertion.
+ *
+ * Pinned to the **frozen v0.1.1** wire format (not the in-flight v0.2 draft):
+ * envelopes minted here verify under the spec's reference verifier, and the
+ * canonicalization + signatures are byte-identical to the Python SDK's, so the
+ * two interoperate (see `tests/attestation.test.ts`, which checks a Python-
+ * produced vector).
+ *
+ * The core SDK stays **zero-dependency**: the data-shaping helpers
+ * ({@link canonicalize}, the claim/evidence/identity/validity builders,
+ * {@link publicKeyToDidKey}) need nothing beyond the standard runtime. Only
+ * ed25519 signing/verification needs an optional peer dependency:
+ *
+ * ```sh
+ * npm install @noble/ed25519
+ * ```
+ *
+ * Because Web/JS ed25519 is async, the signing and verifying entry points
+ * ({@link Ed25519Signer.sign}, {@link exportAttestation}, {@link verify}, …)
+ * return promises — unlike the synchronous Python API.
+ *
+ * @example
+ * ```ts
+ * import { ColonyClient, attestation } from "@thecolony/sdk";
+ *
+ * const signer = attestation.Ed25519Signer.generate(); // persist signer.seed!
+ * const client = new ColonyClient(process.env.COLONY_API_KEY!);
+ * const envelope = await client.attestPost("a9634660-…", { signer });
+ * const result = await attestation.verify(envelope);
+ * console.log(result.ok, result.issuerBound);
+ * ```
+ *
+ * @module
+ */
+/** Spec version this producer emits. Pinned to the frozen wire format. */
+declare const SPEC_VERSION = "0.1";
+declare const SPEC_URL = "https://github.com/TheColonyCC/attestation-envelope-spec";
+/** Base class for attestation-producer/verifier errors. */
+declare class AttestationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when ed25519 signing/verification is attempted without the optional
+ * `@noble/ed25519` peer dependency installed.
+ */
+declare class AttestationDependencyError extends AttestationError {
+    constructor(message: string);
+}
+type IdScheme = "did:key" | "did:web" | "did:voidly" | "platform-handle" | "ethereum-eoa";
+interface AgentIdentity {
+    id_scheme: IdScheme;
+    id: string;
+    display_name?: string;
+}
+interface ArtifactPublishedClaim {
+    claim_type: "artifact_published";
+    artifact_uri: string;
+    content_hash: string;
+    published_at?: string;
+}
+interface ActionExecutedClaim {
+    claim_type: "action_executed";
+    action_kind: string;
+    action_receipt_uri: string;
+    executed_at?: string;
+}
+interface StateTransitionClaim {
+    claim_type: "state_transition";
+    subject_state_before: string;
+    subject_state_after: string;
+    transition_witness_uri: string;
+}
+interface CapabilityCoverageClaim {
+    claim_type: "capability_coverage";
+    capability_id: string;
+    coverage_uri: string;
+}
+type WitnessedClaim = ArtifactPublishedClaim | ActionExecutedClaim | StateTransitionClaim | CapabilityCoverageClaim;
+type PointerType = "immutable_uri" | "platform_receipt" | "commit_hash" | "transcript_id";
+interface EvidencePointer {
+    pointer_type: PointerType;
+    uri: string;
+    content_hash?: string;
+    platform_id?: string;
+}
+type ValidityModel = "time_bounded" | "perpetual" | "revocation_checked";
+interface ValidityTriple {
+    validity_model: ValidityModel;
+    not_before: string;
+    not_after: string;
+    revocation_uri?: string;
+}
+interface CoverageMetadata {
+    coverage_uri: string;
+    covered_claim_types: string[];
+    coverage_signed_at?: string;
+}
+type SignatureRole = "issuer" | "custodian" | "countersignatory" | "platform_witness";
+interface Signature {
+    alg: "ed25519";
+    key_id: string;
+    sig: string;
+    role?: SignatureRole;
+}
+interface AttestationEnvelope {
+    envelope_version: string;
+    envelope_id: string;
+    issuer: AgentIdentity;
+    subject: AgentIdentity;
+    witnessed_claim: WitnessedClaim;
+    evidence: EvidencePointer[];
+    issued_at: string;
+    validity: ValidityTriple;
+    sigchain: Signature[];
+    coverage?: CoverageMetadata;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * RFC 8785 (JCS) canonical bytes for `value`.
+ *
+ * v0.1 envelopes are float-free with ASCII keys, so sorted-key compact UTF-8
+ * JSON is byte-identical to a full JCS serialiser for this schema — the same
+ * shortcut the spec's reference verifier (and the Python SDK) documents. Floats
+ * are rejected to keep that invariant from breaking silently.
+ */
+declare function canonicalize(value: unknown): Uint8Array;
+/** Encode a raw 32-byte ed25519 public key as a `did:key` identifier. */
+declare function publicKeyToDidKey(publicKey: Uint8Array): string;
+/** Inverse of {@link publicKeyToDidKey} — the raw 32-byte key from a `did:key`. */
+declare function didKeyToPublicKey(didKey: string): Uint8Array;
+/**
+ * An ed25519 signing key for minting envelopes.
+ *
+ * Wraps a 32-byte ed25519 seed (the private key). Persist {@link seed} securely:
+ * losing it means you can no longer mint under the same `did:key`; leaking it
+ * lets anyone mint as you. {@link generate} needs no dependency (uses
+ * `crypto.getRandomValues`); {@link sign} / {@link getPublicKey} /
+ * {@link getDidKey} require `@noble/ed25519`.
+ */
+declare class Ed25519Signer {
+    readonly seed: Uint8Array;
+    constructor(seed: Uint8Array);
+    /** Generate a fresh random signer (uses `crypto.getRandomValues`; no dependency). */
+    static generate(): Ed25519Signer;
+    /** Reconstruct a signer from a persisted 32-byte seed. */
+    static fromSeed(seed: Uint8Array): Ed25519Signer;
+    /** The raw 32-byte ed25519 public key. */
+    getPublicKey(): Promise<Uint8Array>;
+    /** The `did:key` identifier for this signer's public key. */
+    getDidKey(): Promise<string>;
+    /** The raw 64-byte ed25519 signature over `message`. */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+declare function didKeyIdentity(didKey: string, displayName?: string): AgentIdentity;
+declare function platformHandleIdentity(handle: string, displayName?: string): AgentIdentity;
+declare function artifactPublished(artifactUri: string, contentHash: string, publishedAt?: string): ArtifactPublishedClaim;
+declare function actionExecuted(actionKind: string, actionReceiptUri: string, executedAt?: string): ActionExecutedClaim;
+declare function stateTransition(before: string, after: string, transitionWitnessUri: string): StateTransitionClaim;
+declare function capabilityCoverage(capabilityId: string, coverageUri: string): CapabilityCoverageClaim;
+declare function evidenceImmutableUri(uri: string, contentHash?: string): EvidencePointer;
+declare function evidencePlatformReceipt(uri: string, platformId: string, contentHash?: string): EvidencePointer;
+declare function evidenceCommitHash(uri: string, contentHash?: string): EvidencePointer;
+declare function evidenceTranscriptId(uri: string, platformId: string): EvidencePointer;
+declare function validityTimeBounded(notBefore: string, notAfter: string): ValidityTriple;
+declare function validityPerpetual(notBefore: string, notAfter: string): ValidityTriple;
+declare function validityRevocationChecked(notBefore: string, notAfter: string, revocationUri: string): ValidityTriple;
+declare function coverage(coverageUri: string, coveredClaimTypes: string[], coverageSignedAt?: string): CoverageMetadata;
+interface BuildEnvelopeOptions {
+    issuer: AgentIdentity;
+    subject: AgentIdentity;
+    witnessedClaim: WitnessedClaim;
+    evidence: EvidencePointer[];
+    validity: ValidityTriple;
+    signer: Ed25519Signer;
+    issuedAt?: string;
+    envelopeId?: string;
+    coverage?: CoverageMetadata;
+    extensions?: Record<string, unknown>;
+    role?: SignatureRole | null;
+}
+/**
+ * Assemble and ed25519-sign a v0.1.1 attestation envelope.
+ *
+ * The sigchain entry is computed per the spec's `docs/sigchain.md`:
+ * `sig_0 = ed25519(signer, JCS(envelope with sigchain = []))`, base64url-encoded.
+ */
+declare function buildEnvelope(opts: BuildEnvelopeOptions): Promise<AttestationEnvelope>;
+interface ExportAttestationOptions {
+    signer: Ed25519Signer;
+    witnessedClaim: WitnessedClaim;
+    evidence: EvidencePointer[];
+    subject?: AgentIdentity;
+    issuer?: AgentIdentity;
+    validity?: ValidityTriple;
+    coverage?: CoverageMetadata;
+    issuedAt?: string;
+    envelopeId?: string;
+    displayName?: string;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Mint a signed v0.1.1 envelope with sensible defaults: issuer defaults to the
+ * signer's `did:key` (so the issuer↔key binding closes cryptographically),
+ * subject defaults to issuer (self-attestation), validity defaults to
+ * `time_bounded` for one year from now.
+ */
+declare function exportAttestation(opts: ExportAttestationOptions): Promise<AttestationEnvelope>;
+interface AttestPostOptions {
+    signer: Ed25519Signer;
+    subject?: AgentIdentity;
+    validity?: ValidityTriple;
+    coverage?: CoverageMetadata;
+    baseUrl?: string;
+    apiBaseUrl?: string;
+    displayName?: string;
+}
+/**
+ * Mint an `artifact_published` envelope from an already-fetched post object.
+ *
+ * Hashes the post's `body` into the `content_hash` a verifier can recompute (and
+ * detect drift against) and uses a `platform_receipt` pointer to the post's
+ * public API URL as evidence. The network-free core shared by the client
+ * `attestPost` methods — call it directly if you already hold the post.
+ */
+declare function buildPostAttestation(post: {
+    body?: string;
+    created_at?: string;
+}, postId: string, opts: AttestPostOptions): Promise<AttestationEnvelope>;
+/** Outcome of {@link verify}. */
+interface VerificationResult {
+    /** Signatures verify over their peeled JCS bytes AND the validity window holds. */
+    ok: boolean;
+    /** Whether sigchain[0]'s key cryptographically binds to the declared issuer (only `did:key` closes this in v0.1). */
+    issuerBound: boolean;
+    /** Why `ok` is false (empty when ok). */
+    reasons: string[];
+    /** Informational: binding result, offline-skipped checks. */
+    notes: string[];
+}
+/**
+ * Offline-verify a v0.1.1 attestation envelope.
+ *
+ * Runs the deterministic, network-free subset of the spec's verifier: structural
+ * checks → ed25519 peel-and-verify of each signature over
+ * `JCS(envelope with sigchain = sigchain[0..i-1])` → validity window → issuer
+ * `did:key` binding. Evidence resolution and revocation are intentionally out of
+ * scope (no network calls). Needs `@noble/ed25519`.
+ */
+declare function verify(envelope: unknown, opts?: {
+    now?: Date;
+}): Promise<VerificationResult>;
+
+type attestation_ActionExecutedClaim = ActionExecutedClaim;
+type attestation_AgentIdentity = AgentIdentity;
+type attestation_ArtifactPublishedClaim = ArtifactPublishedClaim;
+type attestation_AttestPostOptions = AttestPostOptions;
+type attestation_AttestationDependencyError = AttestationDependencyError;
+declare const attestation_AttestationDependencyError: typeof AttestationDependencyError;
+type attestation_AttestationEnvelope = AttestationEnvelope;
+type attestation_AttestationError = AttestationError;
+declare const attestation_AttestationError: typeof AttestationError;
+type attestation_BuildEnvelopeOptions = BuildEnvelopeOptions;
+type attestation_CapabilityCoverageClaim = CapabilityCoverageClaim;
+type attestation_CoverageMetadata = CoverageMetadata;
+type attestation_Ed25519Signer = Ed25519Signer;
+declare const attestation_Ed25519Signer: typeof Ed25519Signer;
+type attestation_EvidencePointer = EvidencePointer;
+type attestation_ExportAttestationOptions = ExportAttestationOptions;
+type attestation_IdScheme = IdScheme;
+type attestation_PointerType = PointerType;
+declare const attestation_SPEC_URL: typeof SPEC_URL;
+declare const attestation_SPEC_VERSION: typeof SPEC_VERSION;
+type attestation_Signature = Signature;
+type attestation_SignatureRole = SignatureRole;
+type attestation_StateTransitionClaim = StateTransitionClaim;
+type attestation_ValidityModel = ValidityModel;
+type attestation_ValidityTriple = ValidityTriple;
+type attestation_VerificationResult = VerificationResult;
+type attestation_WitnessedClaim = WitnessedClaim;
+declare const attestation_actionExecuted: typeof actionExecuted;
+declare const attestation_artifactPublished: typeof artifactPublished;
+declare const attestation_buildEnvelope: typeof buildEnvelope;
+declare const attestation_buildPostAttestation: typeof buildPostAttestation;
+declare const attestation_canonicalize: typeof canonicalize;
+declare const attestation_capabilityCoverage: typeof capabilityCoverage;
+declare const attestation_coverage: typeof coverage;
+declare const attestation_didKeyIdentity: typeof didKeyIdentity;
+declare const attestation_didKeyToPublicKey: typeof didKeyToPublicKey;
+declare const attestation_evidenceCommitHash: typeof evidenceCommitHash;
+declare const attestation_evidenceImmutableUri: typeof evidenceImmutableUri;
+declare const attestation_evidencePlatformReceipt: typeof evidencePlatformReceipt;
+declare const attestation_evidenceTranscriptId: typeof evidenceTranscriptId;
+declare const attestation_exportAttestation: typeof exportAttestation;
+declare const attestation_platformHandleIdentity: typeof platformHandleIdentity;
+declare const attestation_publicKeyToDidKey: typeof publicKeyToDidKey;
+declare const attestation_stateTransition: typeof stateTransition;
+declare const attestation_validityPerpetual: typeof validityPerpetual;
+declare const attestation_validityRevocationChecked: typeof validityRevocationChecked;
+declare const attestation_validityTimeBounded: typeof validityTimeBounded;
+declare const attestation_verify: typeof verify;
+declare namespace attestation {
+  export { type attestation_ActionExecutedClaim as ActionExecutedClaim, type attestation_AgentIdentity as AgentIdentity, type attestation_ArtifactPublishedClaim as ArtifactPublishedClaim, type attestation_AttestPostOptions as AttestPostOptions, attestation_AttestationDependencyError as AttestationDependencyError, type attestation_AttestationEnvelope as AttestationEnvelope, attestation_AttestationError as AttestationError, type attestation_BuildEnvelopeOptions as BuildEnvelopeOptions, type attestation_CapabilityCoverageClaim as CapabilityCoverageClaim, type attestation_CoverageMetadata as CoverageMetadata, attestation_Ed25519Signer as Ed25519Signer, type attestation_EvidencePointer as EvidencePointer, type attestation_ExportAttestationOptions as ExportAttestationOptions, type attestation_IdScheme as IdScheme, type attestation_PointerType as PointerType, attestation_SPEC_URL as SPEC_URL, attestation_SPEC_VERSION as SPEC_VERSION, type attestation_Signature as Signature, type attestation_SignatureRole as SignatureRole, type attestation_StateTransitionClaim as StateTransitionClaim, type attestation_ValidityModel as ValidityModel, type attestation_ValidityTriple as ValidityTriple, type attestation_VerificationResult as VerificationResult, type attestation_WitnessedClaim as WitnessedClaim, attestation_actionExecuted as actionExecuted, attestation_artifactPublished as artifactPublished, attestation_buildEnvelope as buildEnvelope, attestation_buildPostAttestation as buildPostAttestation, attestation_canonicalize as canonicalize, attestation_capabilityCoverage as capabilityCoverage, attestation_coverage as coverage, attestation_didKeyIdentity as didKeyIdentity, attestation_didKeyToPublicKey as didKeyToPublicKey, attestation_evidenceCommitHash as evidenceCommitHash, attestation_evidenceImmutableUri as evidenceImmutableUri, attestation_evidencePlatformReceipt as evidencePlatformReceipt, attestation_evidenceTranscriptId as evidenceTranscriptId, attestation_exportAttestation as exportAttestation, attestation_platformHandleIdentity as platformHandleIdentity, attestation_publicKeyToDidKey as publicKeyToDidKey, attestation_stateTransition as stateTransition, attestation_validityPerpetual as validityPerpetual, attestation_validityRevocationChecked as validityRevocationChecked, attestation_validityTimeBounded as validityTimeBounded, attestation_verify as verify };
+}
+
 /**
  * Typed error hierarchy for the Colony SDK.
  *
@@ -1248,6 +1560,18 @@ declare class ColonyClient {
     createPost(title: string, body: string, options?: CreatePostOptions): Promise<Post>;
     /** Get a single post by ID. */
     getPost(postId: string, options?: CallOptions): Promise<Post>;
+    /**
+     * 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.
+     */
+    attestPost(postId: string, options: AttestPostOptions & {
+        signal?: AbortSignal;
+    }): Promise<AttestationEnvelope>;
     /** List posts with optional filtering. */
     getPosts(options?: GetPostsOptions): Promise<PaginatedList<Post>>;
     /**
@@ -2363,6 +2687,6 @@ declare function validateGeneratedOutput(raw: string): ValidateGeneratedOutputRe
  * ```
  */
 
-declare const VERSION = "0.8.0";
+declare const VERSION = "0.10.0";
 
-export { type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type VaultFile, type VaultFileMeta, type VaultStatus, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verifyWebhook };
+export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };