@truealter/sdk 0.4.1 → 0.5.1

package/dist/index.d.cts

@@ -130,6 +130,7 @@ interface ProvenanceEnvelope {
 }
 interface ProvenancePayload {
     iss: string;
+    aud?: string | string[];
     iat: number;
     exp: number;
     purpose: string;
@@ -188,6 +189,21 @@ interface VerifyProvenanceOptions {
     verifyAtAllowlist?: readonly string[];
     fetch?: typeof fetch;
     now?: number;
+    /**
+     * Expected `iss` claim. Defaults to {@link ALTER_PLATFORM_ISS}
+     * (`"did:alter:platform"`). Pass an explicit value only when verifying
+     * tokens minted by a non-platform issuer (e.g. a test fixture or a
+     * whitelabelled deployment). An empty string disables the check — not
+     * recommended for production use.
+     */
+    expectedIss?: string;
+    /**
+     * Expected `aud` claim. When provided and non-empty, the token's `aud`
+     * claim must contain this value (RFC 7519 §4.1.3). Pass an empty string
+     * to disable the check. Defaults to no check (undefined) for backward
+     * compatibility — callers SHOULD supply this in production environments.
+     */
+    expectedAud?: string;
 }
 /**
  * Verify a provenance JWS token against ALTER's published JWKS.
@@ -208,7 +224,15 @@ declare function verifyProvenance(envelope: ProvenanceEnvelope | string, opts?:
  *
  * ALTER signs each tool's input schema at startup and exposes the
  * signatures via the MCP `tools/list` `_meta.signatures` map. This helper
- * checks that each tool's schema hash matches the signed value.
+ * checks that each tool's schema hash matches the signed value, AND
+ * cryptographically verifies the ES256 JWS signature carried in
+ * `sig.signature` / `sig.kid` against the JWKS published at `jwksUrl`.
+ *
+ * H-9 remediation: previously only the schema hash was verified; the
+ * `sig.signature` and `sig.kid` fields were carried but never checked,
+ * allowing a hostile MCP server to substitute a fake tool schema whose
+ * hash matched a maliciously crafted `schema_hash` without needing the
+ * signing key.
  */
 interface SignedToolDefinition {
     name: string;
@@ -222,10 +246,22 @@ interface ToolSignatureMap {
         kid?: string | null;
     };
 }
-declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap): Promise<{
+interface VerifyToolSignaturesOptions {
+    /**
+     * JWKS URL to verify ES256 signatures against. Must be https.
+     * Defaults to `https://api.truealter.com/.well-known/alter-keys.json`.
+     * When a tool's `signature` field is null/absent, the tool is marked
+     * valid-on-hash (legacy path) and a `warn_no_signature: true` flag is
+     * included in the result.
+     */
+    jwksUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap, opts?: VerifyToolSignaturesOptions): Promise<{
     tool: string;
     valid: boolean;
     reason?: string;
+    warn_no_signature?: boolean;
 }[]>;
 /**
  * Fetch the ALTER public key set. Cached in-process for five minutes.
@@ -361,12 +397,21 @@ interface X402ClientOptions {
     networks?: string[];
     /** Permitted assets. Defaults to `['USDC']`. */
     assets?: string[];
+    /**
+     * Known recipient addresses. Defaults to {@link DEFAULT_RECIPIENT_ALLOWLIST}.
+     * Passing a list here *replaces* the default — include the ALTER canonical
+     * address if you still want it accepted.
+     *
+     * An empty array disables the check entirely (not recommended for production).
+     */
+    recipientAllowlist?: string[];
 }
 declare class X402Client {
     private readonly signer?;
     private readonly maxPerQuery?;
     private readonly networks;
     private readonly assets;
+    private readonly recipientAllowlist;
     constructor(opts?: X402ClientOptions);
     /**
      * Validate the envelope against this client's policy and, if a signer
@@ -407,7 +452,7 @@ interface MCPClientOptions {
     /** Optional x402 client for automatic premium tool payment. */
     x402?: X402Client;
     /**
-     * Q5c per-invocation signing. When present, every `tools/call` is
+     * ES256 per-invocation signing. When present, every `tools/call` is
      * ES256-signed and submitted with the `Mcp-Invocation-Signature`
      * header. The public half of `privateKey` MUST have been
      * registered via `POST /api/v1/agents/keys` against the same API
@@ -416,6 +461,16 @@ interface MCPClientOptions {
      * 2026-04-20).
      */
     signing?: MCPSigningOptions;
+    /**
+     * Extra HTTP headers added to every request. Useful when the endpoint
+     * sits behind an edge gate that requires its own credentials —
+     * e.g. Cloudflare Access service tokens (`CF-Access-Client-Id` +
+     * `CF-Access-Client-Secret`). Protocol-level headers (`Content-Type`,
+     * `Accept`) and ALTER-internal headers (`X-ALTER-API-Key`,
+     * `Mcp-Session-Id`, `Mcp-Invocation-Signature`) always win over
+     * collisions here.
+     */
+    extraHeaders?: Record<string, string>;
 }
 interface MCPSigningOptions {
     /** The signing-key id pre-registered with the server. */
@@ -473,6 +528,7 @@ declare class MCPClient {
     private readonly clientInfo;
     private readonly x402?;
     private readonly signing?;
+    private readonly extraHeaders?;
     private requestCounter;
     private initialised;
     constructor(opts?: MCPClientOptions);
@@ -605,7 +661,7 @@ interface ListArchetypesOutput {
 }
 /** (free) verify_identity — Verify a person is registered with ALTER and validate optional claims */
 interface VerifyIdentityInput {
-    candidate_id: string;
+    member_id: string;
     email?: string;
     claims?: {
         archetype?: string;
@@ -620,7 +676,7 @@ interface VerifyIdentityInput {
 interface VerifyIdentityOutput {
     ok: boolean;
     verified: boolean;
-    candidate_id?: string;
+    member_id?: string;
     engagement_level?: EngagementLevel;
     archetype?: Archetype;
     claims_valid?: boolean;
@@ -640,7 +696,7 @@ interface InitiateAssessmentOutput {
 }
 /** (free) get_engagement_level — Get a person's identity depth and available query tiers */
 interface GetEngagementLevelInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_engagement_level — output */
 interface GetEngagementLevelOutput {
@@ -657,12 +713,12 @@ interface GetEngagementLevelOutput {
 }
 /** (free) get_profile — Get a person's profile summary */
 interface GetProfileInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_profile — output */
 interface GetProfileOutput {
     ok: boolean;
-    candidate_id: string;
+    member_id: string;
     assessment_phase?: string;
     archetype?: Archetype;
     engagement_level?: EngagementLevel;
@@ -670,7 +726,7 @@ interface GetProfileOutput {
 }
 /** (free) query_matches — Query matches for a person (tier labels only) */
 interface QueryMatchesInput {
-    candidate_id: string;
+    member_id: string;
     quality_filter?: MatchTier;
     limit?: number;
 }
@@ -687,7 +743,7 @@ interface QueryMatchesOutput {
 }
 /** (free) get_competencies — Get a person's competency portfolio */
 interface GetCompetenciesInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_competencies — output */
 interface GetCompetenciesOutput {
@@ -714,7 +770,7 @@ interface SearchIdentitiesInput {
 interface SearchIdentitiesOutput {
     ok: boolean;
     identities: Array<{
-        candidate_id: string;
+        member_id: string;
         trait_summary: Record<string, number>;
         engagement_level?: EngagementLevel;
     }>;
@@ -722,7 +778,7 @@ interface SearchIdentitiesOutput {
 }
 /** (free) get_identity_earnings — Get accrued Identity Income earnings for a person */
 interface GetIdentityEarningsInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_identity_earnings — output */
 interface GetIdentityEarningsOutput {
@@ -730,7 +786,7 @@ interface GetIdentityEarningsOutput {
     total_earned_usd: number;
     pending_usd: number;
     transaction_count: number;
-    unique_employers: number;
+    unique_orgs: number;
 }
 /** (free) get_network_stats — Get aggregate ALTER network statistics */
 interface GetNetworkStatsInput {
@@ -756,7 +812,7 @@ interface RecommendToolOutput {
 }
 /** (free) get_identity_trust_score — Get the trust score for an identity based on query diversity */
 interface GetIdentityTrustScoreInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_identity_trust_score — output */
 interface GetIdentityTrustScoreOutput {
@@ -779,7 +835,7 @@ interface CheckAssessmentStatusOutput {
 }
 /** (free) get_earning_summary — Get an aggregated x402 earning summary for a person */
 interface GetEarningSummaryInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_earning_summary — output */
 interface GetEarningSummaryOutput {
@@ -819,7 +875,7 @@ interface GetAgentPortfolioOutput {
 }
 /** (free) get_privacy_budget — Check privacy budget status for a person (24h rolling window) */
 interface GetPrivacyBudgetInput {
-    candidate_id: string;
+    member_id: string;
 }
 /** (free) get_privacy_budget — output */
 interface GetPrivacyBudgetOutput {
@@ -922,13 +978,13 @@ interface AssessTraitsOutput {
 }
 /** (premium L1) get_trait_snapshot — Get the top 5 traits for a person ($0.005) */
 interface GetTraitSnapshotInput {
-    candidate_id: string;
+    member_id: string;
     _payment?: ProvenanceToken;
 }
 /** (premium L1) get_trait_snapshot — output */
 interface GetTraitSnapshotOutput {
     ok: boolean;
-    candidate_id: string;
+    member_id: string;
     archetype: Archetype;
     top_traits: Array<{
         name: string;
@@ -938,13 +994,13 @@ interface GetTraitSnapshotOutput {
 }
 /** (premium L2) get_full_trait_vector — Get the complete trait vector (all 33 traits: 29 continuous + 4 categorical) ($0.01) */
 interface GetFullTraitVectorInput {
-    candidate_id: string;
+    member_id: string;
     _payment?: ProvenanceToken;
 }
 /** (premium L2) get_full_trait_vector — output */
 interface GetFullTraitVectorOutput {
     ok: boolean;
-    candidate_id: string;
+    member_id: string;
     traits: Array<{
         name: string;
         category: string;
@@ -954,7 +1010,7 @@ interface GetFullTraitVectorOutput {
 }
 /** (premium L4) compute_belonging — Compute belonging probability for a person-job pairing ($0.05) */
 interface ComputeBelongingInput {
-    candidate_id: string;
+    member_id: string;
     job_id: string;
     _payment?: ProvenanceToken;
 }
@@ -971,7 +1027,7 @@ interface ComputeBelongingOutput {
 }
 /** (premium L5) get_match_recommendations — Get top N match recommendations for a person ($0.50) */
 interface GetMatchRecommendationsInput {
-    candidate_id: string;
+    member_id: string;
     limit?: number;
     _payment?: ProvenanceToken;
 }
@@ -1004,7 +1060,7 @@ interface GenerateMatchNarrativeOutput {
 }
 /** (premium L2) get_side_quest_graph — Get a person's Side Quest Graph (DP noise ε=1.0) ($0.01) */
 interface GetSideQuestGraphInput {
-    candidate_id: string;
+    member_id: string;
     include_edges?: boolean;
     min_confidence?: number;
     _payment?: ProvenanceToken;
@@ -1012,7 +1068,7 @@ interface GetSideQuestGraphInput {
 /** (premium L2) get_side_quest_graph — output */
 interface GetSideQuestGraphOutput {
     ok: boolean;
-    candidate_id: string;
+    member_id: string;
     domains: Array<{
         label: string;
         confidence: number;
@@ -1027,15 +1083,15 @@ interface GetSideQuestGraphOutput {
 }
 /** (premium L3) query_graph_similarity — Compare two Side Quest Graphs (DP noise ε=0.5) ($0.025) */
 interface QueryGraphSimilarityInput {
-    candidate_a_id: string;
-    candidate_b_id: string;
+    member_a_id: string;
+    member_b_id: string;
     _payment?: ProvenanceToken;
 }
 /** (premium L3) query_graph_similarity — output */
 interface QueryGraphSimilarityOutput {
     ok: boolean;
-    candidate_a_id: string;
-    candidate_b_id: string;
+    member_a_id: string;
+    member_b_id: string;
     domain_overlap: number;
     edge_similarity: number;
     complementarity: number;
@@ -1359,7 +1415,7 @@ interface SignInvocationOptions {
  * Usage:
  *
  * ```ts
- * const header = signInvocation("get_profile", { candidate_id: "abc" }, {
+ * const header = signInvocation("get_profile", { member_id: "abc" }, {
  *   kid, privateKey, handle: "~tester",
  * });
  * fetch(url, { headers: { "Mcp-Invocation-Signature": header } });
@@ -1576,11 +1632,17 @@ declare function sha256(bytes: string | Buffer): string;
  * deterministic ordering is worth the tiny blocking cost.
  */
 
+interface CfAccessCredentials {
+    clientId: string;
+    clientSecret: string;
+}
 interface WireOptions {
     /** Override the endpoint written into every client config. Defaults to DEFAULT_ENDPOINT. */
     endpoint?: string;
     /** Optional API key written into `headers['X-ALTER-API-Key']` for each target. */
     apiKey?: string;
+    /** CF Access service token credentials. Auto-read from ~/.config/alter/cf-access.env when absent. */
+    cfAccess?: CfAccessCredentials;
     /** Restrict to a subset of client ids. Default: every detected client. */
     only?: readonly ClientId[];
     /** Skip any client whose probe said "not installed" even if the caller passed it via `only`. */
@@ -1601,6 +1663,345 @@ interface UnwireReport {
 }
 declare function unwire(): UnwireReport;
 
+/**
+ * @truealter/sdk — alter_homepage MCP tool types
+ *
+ * Wire-format types for the user-authored, externally-queryable identity
+ * homepage surface.
+ *
+ * Tool name note: the wire-format and server-side tool name are
+ * `alter_homepage`. The name `alter_portfolio` is reserved by the
+ * verified-attestations tool in `mcp-alter` (a different concept), so
+ * homepage types ship under `homepage`.
+ *
+ * Wire-format rule: every field name matches the JSON Schema property
+ * name exactly (snake_case). These are passed straight into JSON-RPC
+ * `arguments` and rendered straight from JSON-RPC `result`.
+ */
+/**
+ * Provenance class for a HomepageManifest field. Determines how a
+ * conforming MCP consumer renders the value:
+ *
+ * - `declared`: user wrote the literal value. Render verbatim.
+ * - `derived`: computed from active + consented signals. Render with
+ *   provenance class surfaced to the viewer (e.g. an italic gloss).
+ * - `attested`: verified by a recognised entity (Org Alter, ceremony,
+ *   external attester). Render with provenance + attester surfaced.
+ */
+type HomepageFieldProvenance = "declared" | "derived" | "attested";
+/**
+ * One field of a HomepageManifest. Every field carries its provenance
+ * class so MCP consumers can render appropriately. The `value` shape is
+ * field-specific — this is a discriminated parent; consumers should
+ * narrow on the manifest's field name, not on `value`'s runtime shape.
+ */
+interface HomepageField<T = unknown> {
+    /** The user-facing value. Type depends on which field this is. */
+    value: T;
+    /** Where this value comes from. */
+    provenance: HomepageFieldProvenance;
+    /**
+     * For `attested` fields, the entity that attested. Optional on the
+     * other provenance classes (where it would be redundant).
+     */
+    attester?: string;
+}
+/**
+ * The wire-format manifest returned by `alter_homepage(handle)`.
+ *
+ * Fields are individually optional — a HomepageManifest with only a
+ * handle and an opener is valid. MCP consumers MUST NOT assume any
+ * field other than `handle` is present.
+ */
+interface HomepageManifest {
+    /** The ~handle being queried. Always present. */
+    handle: string;
+    /**
+     * Single-line user-authored self-description. Maximum 240 chars
+     * after NFC normalisation, after the install-time ANSI sanitiser
+     * pass. Always declared-provenance.
+     */
+    whoami?: HomepageField<string>;
+    /**
+     * Rotating or static user-authored line. Maximum 280 chars after
+     * NFC normalisation, after the install-time ANSI sanitiser pass.
+     * The literal `~` substitutes the active handle at render time.
+     * Always declared-provenance.
+     */
+    opener?: HomepageField<string>;
+    /**
+     * Composed-glyph string (from typed primitives). The
+     * sigil is a string of renderer-recognised primitive references —
+     * not raw glyph codes — so different consumers can render the same
+     * sigil distinctly. Provenance is `declared` for user-composed,
+     * `derived` for sigil-from-thread-graph crystallisation.
+     */
+    sigil?: HomepageField<string>;
+    /** User's pronouns (already-shipped surface). Always declared. */
+    pronouns?: HomepageField<string>;
+    /**
+     * List of recognised Seat glyphs the holder is bound to. Provenance
+     * is always `attested` (ceremony-attested, server-side resolved);
+     * `attester` will be `~alter` for protocol-observed Seats.
+     */
+    seats?: HomepageField<readonly string[]>;
+    /**
+     * Glyph from the user's attunement-grade library. Provenance is
+     * `derived` (from the user's identity vector); the underlying
+     * computation is L3-local and the chosen glyph is declared-from-
+     * derived-measure (user picks within a library gated by their
+     * attunement grade).
+     */
+    attunement_glyph?: HomepageField<string>;
+    /**
+     * Optional, opt-in per query context. Coarse Golden-Thread summary;
+     * provenance is `derived`. MCP consumers MUST NOT request this field
+     * by default — only on explicit per-call consent. Consumers in the
+     * workplace/education vertical MUST NOT request this field at all
+     * (clause-4 caller-context gate).
+     */
+    thread_strand?: HomepageField<string>;
+    /**
+     * TOML block of MCP-consumer rendering hints (order, density, etc).
+     * Consumers are free to ignore. Provenance is always `declared`.
+     */
+    render_hints?: HomepageField<Record<string, unknown>>;
+}
+/**
+ * Input arguments for the `alter_homepage` MCP tool.
+ *
+ * The `fields` argument lets a consumer request a subset; omitting it
+ * returns all fields the caller is permitted to read under the consent
+ * + caller-context gates.
+ */
+interface HomepageInput {
+    /** The ~handle to query. */
+    handle: string;
+    /**
+     * Optional whitelist of field names. If omitted, the server returns
+     * all fields the caller is permitted to read. Unknown field names
+     * are silently ignored (forward-compatible — adding a new field does
+     * not break old consumers).
+     */
+    fields?: readonly (keyof HomepageManifest)[];
+}
+/**
+ * Output of the `alter_homepage` MCP tool. The `manifest` field is
+ * always present on `ok: true`; on error, the `error` field carries a
+ * structured reason the user can act on.
+ */
+interface HomepageOutput {
+    ok: boolean;
+    manifest?: HomepageManifest;
+    error?: {
+        code: string;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+}
+/**
+ * Caller-context gate: which categories of caller may read which
+ * provenance classes. Enforced server-side; documented here for SDK
+ * consumers building higher-level wrappers.
+ *
+ * - `workplace` / `education` callers MUST NOT receive `derived` or
+ *   `attested` provenance fields without explicit per-field consent
+ *   (EU AI Act Art 5(1)(d) categorical).
+ * - All other callers may read `declared` and `attested` fields by
+ *   default; `derived` fields require stream-specific consent per
+ *   IaI clause 5.
+ */
+type HomepageCallerVertical = "workplace" | "education" | "personal" | "civic" | "agent" | "unknown";
+/** Maximum sizes from the spec. SDK consumers can use these to validate
+ *  input before sending. Mirrored from
+ *  `docs/technical/alter-portfolio-manifest-v1.md` (forthcoming). */
+declare const HOMEPAGE_LIMITS: {
+    readonly whoami_max_chars: 240;
+    readonly opener_max_chars: 280;
+    readonly pronouns_max_chars: 32;
+    readonly attunement_glyph_max_chars: 16;
+};
+
+/**
+ * @truealter/sdk — theme pack types
+ *
+ * Wire-format types for ALTER theme packs and `themes.lock` composition
+ * manifests. The full specification lives in
+ * `docs/technical/alter-theme-pack-spec-v1.md`.
+ *
+ * These types describe the on-the-wire shape of theme manifests as they
+ * are produced by `alter theme install`, persisted to `themes.lock`,
+ * and shared via the `theme_share` MCP tool. They do NOT describe the
+ * runtime renderer's internal state.
+ *
+ * No runtime side effects, no external imports, ESM-compatible.
+ */
+/** The single allowed `palette.floor` value in v1. New floors require schema bump. */
+type PaletteFloorV1 = "muted-gold";
+/** Enumerated text-style values. Free strings are rejected by the loader. */
+type PaletteText = "default" | "high-contrast" | "warm";
+/** Enumerated status-line slot names. Packs MAY use a permutation of any subset. */
+type StatusLineSlot = "handle" | "attunement" | "seat" | "thread_strand" | "pronouns" | "org";
+/** Enumerated status-line density. */
+type StatusLineDensity = "compact" | "roomy";
+/** Enumerated greeting-register values. Passes to the Mirror voice register selector. */
+type GreetingRegister = "intimate" | "formal" | "playful" | "spare";
+/** Enumerated panel-density values for `alter room`. */
+type PanelDensity = "compact" | "roomy";
+/** `[meta]` section. */
+interface ThemeMeta {
+    name: string;
+    /** SemVer-shaped recommended; informational only. Resolution uses pack_id. */
+    version: string;
+    /** MUST be a ~handle whose D-ID8 public key signs the pack. */
+    author: string;
+    /** ≤ 240 characters after NFC. */
+    description: string;
+    /** OPTIONAL — surfaced by curated resolvers; not rendered by ALTER. */
+    repo?: string;
+    /** OPTIONAL — surfaced by curated resolvers; not rendered by ALTER. */
+    docs_url?: string;
+}
+/** `[palette]` section. Renderer enforces gamut; out-of-gamut packs are rejected. */
+interface ThemePalette {
+    floor: PaletteFloorV1;
+    /** Hex colour clamped to the published accent-slot gamut. */
+    accent: string;
+    text: PaletteText;
+}
+/** `[opener]` section. */
+interface ThemeOpener {
+    /** ≤ 32 entries, each ≤ 240 chars after sanitisation. `~` substitutes the active handle. */
+    library: readonly string[];
+}
+/** `[sigil]` section. All values MUST refer to renderer-shipped typed primitives. */
+interface ThemeSigil {
+    glyph_set: string;
+    trill: string;
+    accent_glyph: string;
+}
+/** `[status_line]` section. */
+interface ThemeStatusLine {
+    /** Permutation of any subset of StatusLineSlot. */
+    order: readonly StatusLineSlot[];
+    density: StatusLineDensity;
+}
+/** `[render_hints]` section. */
+interface ThemeRenderHints {
+    greeting_register: GreetingRegister;
+    panel_density: PanelDensity;
+}
+/** `[assets]` section. Paths MUST be repo-relative without `..` segments. */
+interface ThemeAssets {
+    /** Optional — if omitted, no assets are loaded. */
+    glyphs?: readonly string[];
+}
+/**
+ * Complete pack manifest (the parsed-TOML shape of `theme.toml` v1).
+ *
+ * Closed-world: any unknown top-level key MUST cause the loader to
+ * reject the pack. Parsers consuming an arbitrary TOML file should
+ * narrow against this type rather than infer.
+ */
+interface ThemeManifestV1 {
+    schema_version: 1;
+    meta: ThemeMeta;
+    palette: ThemePalette;
+    opener?: ThemeOpener;
+    sigil?: ThemeSigil;
+    status_line?: ThemeStatusLine;
+    render_hints?: ThemeRenderHints;
+    assets?: ThemeAssets;
+}
+/**
+ * The `.sig` file accompanying every pack. Verification logic lives in
+ * `alter-cli/src/theme/sign.ts`; this is the wire-format type only.
+ */
+interface ThemeSignatureManifest {
+    /** SHA-256 multihash of the canonical-form pack. */
+    pack_id: string;
+    /** ~handle of the signer; MUST equal manifest.meta.author. */
+    signer: string;
+    /** RFC 3339 UTC timestamp at signing time. */
+    signed_at: string;
+    /** `ed25519:<base64url-encoded-signature>`. */
+    sig: string;
+}
+/** One pack entry in the user-side composition lockfile. */
+interface ThemeLockEntry {
+    /**
+     * Where the pack was resolved from. One of:
+     *   - `git+<url>#<ref>`   git-URL pin
+     *   - `@<author>/<name>`  curated-resolver tuple
+     *   - `path:<rel-path>`   local-path pin (for development)
+     */
+    source: string;
+    pack_id: string;
+    signer: string;
+    /** Higher wins on slot conflict; equal priority breaks lex by pack_id. */
+    priority: number;
+}
+/**
+ * The user-side composition manifest. This is the publishable artefact
+ * — what someone shares when they say "here is my ALTER".
+ *
+ * Re-applying the same lockfile against the same renderer version MUST
+ * produce a bit-identical render, modulo the `attunement_glyph` field
+ * which is derived per-render from the user's identity vector.
+ */
+interface ThemesLockV1 {
+    schema_version: 1;
+    /** e.g. "alter-cli/0.5.0" — informational, not load-bearing. */
+    generated_by: string;
+    /** RFC 3339 UTC timestamp at lockfile-write time. */
+    generated_at: string;
+    pack: readonly ThemeLockEntry[];
+    /**
+     * User-side per-slot overrides applied AFTER pack composition. Keys
+     * are dotted slot names (e.g. `palette.accent`, `sigil.trill`).
+     * Values must match the slot's enumerated set or gamut.
+     */
+    overrides?: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * Input arguments for the `theme_share` MCP tool. Sharing emits a 5:1
+ * return event to the sharer (recognition credit + pack citation) and
+ * to the recipient (discovery signal). Implementation lives in
+ * `mcp-alter`.
+ */
+interface ThemeShareInput {
+    /** Recipient ~handle. */
+    to: string;
+    /** Pack source the recipient should resolve. Same shape as ThemeLockEntry.source. */
+    source: string;
+    /** Expected pack_id for verification. Sharer asserts they have verified this. */
+    pack_id: string;
+    /** Expected signer ~handle. Sharer asserts the signature checks against this signer. */
+    signer: string;
+    /** Optional one-line note shown to the recipient on receipt. ≤ 280 chars. */
+    note?: string;
+}
+/** Output of the `theme_share` MCP tool. */
+interface ThemeShareOutput {
+    ok: boolean;
+    share_id?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** v1 schema constants. Mirror the spec at docs/technical/alter-theme-pack-spec-v1.md. */
+declare const THEME_LIMITS: {
+    readonly meta_name_pattern: RegExp;
+    readonly meta_description_max_chars: 240;
+    readonly opener_library_max_entries: 32;
+    readonly opener_entry_max_chars: 240;
+    readonly share_note_max_chars: 280;
+};
+/** Allowed OSC-8 hyperlink schemes. Mirrors §6.2 of the spec. */
+declare const OSC8_ALLOWED_SCHEMES: readonly ["https:", "mailto:"];
+type Osc8AllowedScheme = (typeof OSC8_ALLOWED_SCHEMES)[number];
+
 /**
  * Package metadata — kept in a standalone module so deep imports from
  * `src/wire/` can reference version constants without creating a
@@ -1609,4 +2010,4 @@ declare function unwire(): UnwireReport;
 declare const SDK_NAME = "@truealter/sdk";
 declare const SDK_VERSION = "0.3.0";
 
-export { ALL_CLIENTS, AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, type AlterResolveHandleInput, type AlterResolveHandleOutput, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, CLAUDE_CODE, CLAUDE_DESKTOP, CURSOR, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type ClaudeDesktopConfig, type ClaudeDesktopServerConfig, type ClientId, type ClientPaths, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateClaudeDesktopOptions, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type HelloAgentInput, type HelloAgentOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type InvocationClaims, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPSigningOptions, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, PREMIUM_TOOL_NAMES, type PaymentEnvelope, type ProbeResult, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignInvocationOptions, type SignedToolDefinition, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type UnwireReport, VSCODE, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, type WireOptions, type WireReport, type WireState, type WireTarget, type WireTargetCli, type WireTargetFile, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, canonicalArgsSha256, canonicalStringify, clearDiscoveryCache, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha256, sign, signInvocation, unwire, verify, verifyProvenance, verifyToolSignatures, wire, writeWireState };
+export { ALL_CLIENTS, AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, type AlterResolveHandleInput, type AlterResolveHandleOutput, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, CLAUDE_CODE, CLAUDE_DESKTOP, CURSOR, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type ClaudeDesktopConfig, type ClaudeDesktopServerConfig, type ClientId, type ClientPaths, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateClaudeDesktopOptions, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type GreetingRegister, HOMEPAGE_LIMITS, type HelloAgentInput, type HelloAgentOutput, type HomepageCallerVertical, type HomepageField, type HomepageFieldProvenance, type HomepageInput, type HomepageManifest, type HomepageOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type InvocationClaims, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPSigningOptions, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, OSC8_ALLOWED_SCHEMES, type Osc8AllowedScheme, PREMIUM_TOOL_NAMES, type PaletteFloorV1, type PaletteText, type PanelDensity, type PaymentEnvelope, type ProbeResult, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignInvocationOptions, type SignedToolDefinition, type StatusLineDensity, type StatusLineSlot, THEME_LIMITS, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThemeAssets, type ThemeLockEntry, type ThemeManifestV1, type ThemeMeta, type ThemeOpener, type ThemePalette, type ThemeRenderHints, type ThemeShareInput, type ThemeShareOutput, type ThemeSigil, type ThemeSignatureManifest, type ThemeStatusLine, type ThemesLockV1, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type UnwireReport, VSCODE, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, type WireOptions, type WireReport, type WireState, type WireTarget, type WireTargetCli, type WireTargetFile, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, canonicalArgsSha256, canonicalStringify, clearDiscoveryCache, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha256, sign, signInvocation, unwire, verify, verifyProvenance, verifyToolSignatures, wire, writeWireState };