salt-agent-sdk 0.1.0 → 0.19.0

package/dist/identity.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The fixed set of CLAIM sections an agent may set about itself via
+ * `identity.set` in R1. Per the plan (section 2): "Claim sections (name,
+ * bio, link, avatar, category, price, funding disclosure) are editable by
+ * their subject." Keyed here the way salt-api's registry names them
+ * (snake_case, matching the agent's own existing field names where one
+ * already exists -- `display_name`, `message_price` -- rather than the
+ * plan's prose shorthand).
+ */
+export declare const AGENT_CLAIM_SECTION_KEYS: readonly ["display_name", "bio", "link", "avatar", "category", "message_price", "funding_disclosure"];
+export type AgentClaimSectionKey = (typeof AGENT_CLAIM_SECTION_KEYS)[number];
+/** One line of an agent's "What I can do" list (salt-api 0.107.0): a title of at most 60 characters and an optional one-line detail of at most 120. */
+export interface Capability {
+    title: string;
+    detail?: string;
+}
+/** At most this many capabilities; salt-api refuses more. */
+export declare const MAX_CAPABILITIES = 5;
+/**
+ * What `identity.set` accepts: any subset of the fixed claim vocabulary,
+ * each a plain string value, plus `capabilities` -- the agent's "What I can
+ * do" list, which is what visitors see on its card and what its A2A card's
+ * `skills` are generated from.
+ */
+export type IdentityClaims = Partial<Record<AgentClaimSectionKey, string>> & {
+    capabilities?: Capability[];
+};
+/**
+ * The PROOF sections a card or an identity response can carry, for
+ * reference -- these are never written through this SDK. Kept here (not
+ * just in a comment) so a caller can check `PROOF_SECTION_KEYS.includes(key)`
+ * instead of hardcoding the list a second time.
+ */
+export declare const PROOF_SECTION_KEYS: readonly ["pgp_fingerprint", "salt_did", "verified_did", "health", "trust_score", "rail_address"];
+export type ProofSectionKey = (typeof PROOF_SECTION_KEYS)[number];
+export type IdentitySectionKind = "claim" | "proof";
+/**
+ * One row of the OWNER's own identity view (`GET /api/v1/identity` /
+ * `PATCH /api/v1/identity/sections`) -- richer than what a public card
+ * serves, since only the subject (or Salt, for a proof) ever sees `scope`,
+ * `editable_by`, `checked_by`.
+ */
+export interface IdentitySection {
+    key: string;
+    label: string;
+    value: string | null;
+    /** "everyone" in R1 -- other scopes (`verified contacts`, `named`, `nobody`) ship in R2. */
+    scope: string;
+    kind: IdentitySectionKind;
+    /** Who may edit this section's value -- null/absent for a proof. */
+    editable_by?: string | null;
+    /** Who checked and signed this section -- null/absent for a claim. */
+    checked_by?: string | null;
+}
+export interface IdentitySections {
+    sections: IdentitySection[];
+    /** The public, signed card this identity is served as -- see `card()`. */
+    card_url: string;
+}
+export interface CardSaltIdentity {
+    did?: string;
+    pgpFingerprint?: string;
+    /** Present only once Salt has actually verified a DIFFERENT, externally-verified identity for the subject. */
+    verifiedDid?: string;
+}
+/**
+ * One section as it rides on a PUBLIC signed card: just `{key, value,
+ * proof}`. `proof` is `null` for a claim; any other value marks a proof
+ * section Salt itself checked and signed ("Checked by Salt.", plan section
+ * 6) -- this SDK never inspects what shape a non-null proof takes, since
+ * that is Salt's business, not the reader's.
+ */
+export interface CardSection {
+    key: string;
+    value: string | null;
+    proof: unknown;
+}
+export interface CardSignatureEntry {
+    protected: string;
+    signature: string;
+}
+/**
+ * The shape `AgentCardSigner.sign` produces: an A2A AgentCard (or, once
+ * `GET /api/v1/users/:username/card.json` ships, the same shape for a
+ * person) plus `sections` and, when a signing key is configured,
+ * `signatures`. Left open (`[key: string]: unknown`) for every other A2A
+ * field (`name`, `description`, `supportedInterfaces`, `capabilities`,
+ * `skills`, ...) this module has no reason to type narrowly.
+ */
+export interface SignedCard {
+    saltIdentity?: CardSaltIdentity;
+    sections?: CardSection[];
+    signatures?: CardSignatureEntry[];
+    [key: string]: unknown;
+}
+/** Thrown by `verifySignedCard` (and so by `client.card()`) for any card whose signature this SDK cannot confirm -- untrusted, tampered, unsigned, or signed by a key this deployment doesn't publish. Never returned as `verified: false`; a card either verifies or this throws. */
+export declare class IdentityCardInvalidError extends Error {
+    constructor(message: string);
+}
+/** One entry of the Web Bot Auth key directory (`/.well-known/http-message-signatures-directory`) -- see salt-api's `SaltSigningKey#public_jwk`. */
+export interface Ed25519Jwk {
+    kty: string;
+    crv: string;
+    kid?: string;
+    x: string;
+}
+export declare class JcsUnsupportedValueError extends Error {
+}
+/**
+ * Canonicalizes `value` exactly the way salt-api's `Jcs.canonicalize` does:
+ * object keys sorted by UTF-16 code unit (plain `Array#sort` on strings
+ * already does this in JS, matching Ruby's default `String#<=>` for the
+ * ASCII-only keys a card uses), no whitespace, integers as bare digits,
+ * strings via JSON string escaping, and a hard refusal on anything else
+ * (a non-integer number, undefined, a function) rather than guessing at a
+ * serialization another implementation wouldn't match.
+ */
+export declare function canonicalizeJcs(value: unknown): string;
+export declare function base64urlEncode(bytes: Buffer): string;
+export declare function base64urlDecode(str: string): Buffer;
+export interface CardSignatureHeader {
+    alg?: string;
+    kid?: string;
+}
+/**
+ * Parses (never verifies) `card`'s first signature's protected header --
+ * just enough to read `kid` without a network round trip. Used by
+ * `client.card()` to notice a kid its cached key set doesn't have (Salt
+ * rotated its signing key since the last directory fetch) and force one
+ * refetch BEFORE spending a verification attempt that would otherwise fail
+ * for a perfectly legitimate card. Returns undefined for a card with no
+ * signature at all or an unparseable header -- `verifySignedCard` raises
+ * the actual, specific error for those cases at verify time; this helper
+ * only ever informs a caching decision.
+ */
+export declare function parseCardSignatureHeader(card: SignedCard): CardSignatureHeader | undefined;
+/**
+ * Verifies `card`'s first signature against the Web Bot Auth key directory
+ * entries in `jwks`, reconstructing the signing input exactly the way
+ * `AgentCardSigner.verify` does server-side: `protected_b64` is reused
+ * verbatim from the card (never recomputed -- only the payload is), the
+ * payload is the JCS canonicalization of the card with `signatures`
+ * removed, and the whole thing is Ed25519-verified with no digest
+ * (RFC 8032 pure EdDSA, not Ed25519ph).
+ *
+ * Throws `IdentityCardInvalidError` for every failure mode -- no signature
+ * at all, an unparseable protected header, an unsupported algorithm, no
+ * matching published key, or a signature that doesn't match -- so a caller
+ * never has to remember to check a boolean before trusting the result. This
+ * function itself never refetches anything -- see `parseCardSignatureHeader`
+ * for the kid-rotation retry, which happens in client.ts BEFORE this is
+ * called a second time with a freshened `jwks`.
+ */
+export declare function verifySignedCard(card: SignedCard, jwks: Ed25519Jwk[]): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/identity.js

@@ -0,0 +1,196 @@
+"use strict";
+// Identity on Salt (design-fleet/runs/2026-09-22-identity/plan.md): the
+// signed card Salt already serves for agents (A2A AgentCard, 0.72.0) made
+// editable, section by section. This is R1 only: `identity.set`/`identity.get`
+// on the SDK surface (plan section 7) -- reading/writing an agent's own
+// CLAIM sections, and fetching + verifying anyone's signed public card.
+// `identity.share` (an E2E slice into a chat) and `onIdentityAsk` are later
+// releases, and there is deliberately no `setScope` here at all: scope is
+// owner-authenticated through the agent-management API only (an agent may
+// state a claim, never decide who else gets to see it).
+//
+// The card vocabulary is fixed (plan section 9.5 -- "like the Cards block
+// vocabulary; a new section is a release"), split into two kinds:
+//   - CLAIM sections: the subject's own word about themselves. An agent may
+//     set its own claim sections via `identity.set`. Never signed as true --
+//     only signed as "this is what they said".
+//   - PROOF sections (pgp fingerprint, Salt DID, verified DID, health, trust
+//     score, rail address): read-only, computed and signed by Salt itself.
+//     No client-side API sets these -- they exist here only so a reader of
+//     a fetched card can tell a proof row from a claim row and never launder
+//     one as the other (plan section 6: "A proof glyph on a claim row would
+//     launder the claim").
+//
+// Card signing (see salt-api's AgentCardSigner + Jcs + SaltSigningKey,
+// read to get these bytes exactly right): a JWS-shaped (RFC 7515)
+// signature over the card's own RFC 8785 canonical JSON (JCS), flattened
+// without a `payload` field -- the payload IS the card itself, minus
+// `signatures`. `canonicalizeJcs` below is a deliberately narrow port of
+// salt-api's Jcs.rb: only what an identity card ever contains (nested
+// objects/arrays, strings, booleans, null, integers), sorted by UTF-16
+// code unit (JS's default string sort already does this for the plain
+// ASCII keys a card uses). A float reaching it is a bug in the caller, so
+// it throws rather than guessing at a serialization another implementation
+// wouldn't match.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JcsUnsupportedValueError = exports.IdentityCardInvalidError = exports.PROOF_SECTION_KEYS = exports.MAX_CAPABILITIES = exports.AGENT_CLAIM_SECTION_KEYS = void 0;
+exports.canonicalizeJcs = canonicalizeJcs;
+exports.base64urlEncode = base64urlEncode;
+exports.base64urlDecode = base64urlDecode;
+exports.parseCardSignatureHeader = parseCardSignatureHeader;
+exports.verifySignedCard = verifySignedCard;
+const node_crypto_1 = require("node:crypto");
+// --- Section vocabulary --------------------------------------------------
+/**
+ * The fixed set of CLAIM sections an agent may set about itself via
+ * `identity.set` in R1. Per the plan (section 2): "Claim sections (name,
+ * bio, link, avatar, category, price, funding disclosure) are editable by
+ * their subject." Keyed here the way salt-api's registry names them
+ * (snake_case, matching the agent's own existing field names where one
+ * already exists -- `display_name`, `message_price` -- rather than the
+ * plan's prose shorthand).
+ */
+exports.AGENT_CLAIM_SECTION_KEYS = [
+    "display_name",
+    "bio",
+    "link",
+    "avatar",
+    "category",
+    "message_price",
+    "funding_disclosure",
+];
+/** At most this many capabilities; salt-api refuses more. */
+exports.MAX_CAPABILITIES = 5;
+/**
+ * The PROOF sections a card or an identity response can carry, for
+ * reference -- these are never written through this SDK. Kept here (not
+ * just in a comment) so a caller can check `PROOF_SECTION_KEYS.includes(key)`
+ * instead of hardcoding the list a second time.
+ */
+exports.PROOF_SECTION_KEYS = [
+    "pgp_fingerprint",
+    "salt_did",
+    "verified_did",
+    "health",
+    "trust_score",
+    "rail_address",
+];
+/** Thrown by `verifySignedCard` (and so by `client.card()`) for any card whose signature this SDK cannot confirm -- untrusted, tampered, unsigned, or signed by a key this deployment doesn't publish. Never returned as `verified: false`; a card either verifies or this throws. */
+class IdentityCardInvalidError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentityCardInvalid";
+    }
+}
+exports.IdentityCardInvalidError = IdentityCardInvalidError;
+// --- RFC 8785 JCS (narrow port of salt-api's Jcs.rb) ---------------------
+class JcsUnsupportedValueError extends Error {
+}
+exports.JcsUnsupportedValueError = JcsUnsupportedValueError;
+/**
+ * Canonicalizes `value` exactly the way salt-api's `Jcs.canonicalize` does:
+ * object keys sorted by UTF-16 code unit (plain `Array#sort` on strings
+ * already does this in JS, matching Ruby's default `String#<=>` for the
+ * ASCII-only keys a card uses), no whitespace, integers as bare digits,
+ * strings via JSON string escaping, and a hard refusal on anything else
+ * (a non-integer number, undefined, a function) rather than guessing at a
+ * serialization another implementation wouldn't match.
+ */
+function canonicalizeJcs(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new JcsUnsupportedValueError(`canonicalizeJcs: unsupported non-integer number ${value}`);
+        }
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => canonicalizeJcs(v)).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return "{" + keys.map((k) => `${JSON.stringify(k)}:${canonicalizeJcs(obj[k])}`).join(",") + "}";
+    }
+    throw new JcsUnsupportedValueError(`canonicalizeJcs: unsupported value of type ${typeof value}`);
+}
+// --- base64url (no padding), matching SaltSigningKey.b64/unb64 ----------
+function base64urlEncode(bytes) {
+    return bytes.toString("base64url");
+}
+function base64urlDecode(str) {
+    return Buffer.from(str, "base64url");
+}
+/**
+ * Parses (never verifies) `card`'s first signature's protected header --
+ * just enough to read `kid` without a network round trip. Used by
+ * `client.card()` to notice a kid its cached key set doesn't have (Salt
+ * rotated its signing key since the last directory fetch) and force one
+ * refetch BEFORE spending a verification attempt that would otherwise fail
+ * for a perfectly legitimate card. Returns undefined for a card with no
+ * signature at all or an unparseable header -- `verifySignedCard` raises
+ * the actual, specific error for those cases at verify time; this helper
+ * only ever informs a caching decision.
+ */
+function parseCardSignatureHeader(card) {
+    const sigEntry = card.signatures?.[0];
+    if (!sigEntry?.protected)
+        return undefined;
+    try {
+        return JSON.parse(base64urlDecode(sigEntry.protected).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verifies `card`'s first signature against the Web Bot Auth key directory
+ * entries in `jwks`, reconstructing the signing input exactly the way
+ * `AgentCardSigner.verify` does server-side: `protected_b64` is reused
+ * verbatim from the card (never recomputed -- only the payload is), the
+ * payload is the JCS canonicalization of the card with `signatures`
+ * removed, and the whole thing is Ed25519-verified with no digest
+ * (RFC 8032 pure EdDSA, not Ed25519ph).
+ *
+ * Throws `IdentityCardInvalidError` for every failure mode -- no signature
+ * at all, an unparseable protected header, an unsupported algorithm, no
+ * matching published key, or a signature that doesn't match -- so a caller
+ * never has to remember to check a boolean before trusting the result. This
+ * function itself never refetches anything -- see `parseCardSignatureHeader`
+ * for the kid-rotation retry, which happens in client.ts BEFORE this is
+ * called a second time with a freshened `jwks`.
+ */
+function verifySignedCard(card, jwks) {
+    const sigEntry = card.signatures?.[0];
+    if (!sigEntry || !sigEntry.protected || !sigEntry.signature) {
+        throw new IdentityCardInvalidError("This card carries no signature -- Salt has not signed it (signing may be unconfigured on this deployment, or this isn't really a Salt identity card).");
+    }
+    const header = parseCardSignatureHeader(card);
+    if (!header) {
+        throw new IdentityCardInvalidError("This card's signature header could not be parsed.");
+    }
+    if (header.alg !== "EdDSA") {
+        throw new IdentityCardInvalidError(`This card is signed with an unsupported algorithm (${header.alg ?? "none"}); only EdDSA (Ed25519) is trusted.`);
+    }
+    const key = jwks.find((k) => k.kid === header.kid && k.kty === "OKP" && k.crv === "Ed25519");
+    if (!key) {
+        throw new IdentityCardInvalidError(`No published Salt key matches this card's signing key id (${header.kid ?? "unknown"}).`);
+    }
+    const { signatures: _signatures, ...unsigned } = card;
+    const payloadB64 = base64urlEncode(Buffer.from(canonicalizeJcs(unsigned), "utf8"));
+    const signingInput = Buffer.from(`${sigEntry.protected}.${payloadB64}`, "utf8");
+    const signatureBytes = base64urlDecode(sigEntry.signature);
+    const publicKey = (0, node_crypto_1.createPublicKey)({ key: { kty: "OKP", crv: "Ed25519", x: key.x }, format: "jwk" });
+    // No digest -- Ed25519 (pure EdDSA) signs the message directly, mirroring
+    // SaltSigningKey#sign/#verify server-side (`@pkey.sign(nil, message)`).
+    const ok = (0, node_crypto_1.verify)(null, signingInput, publicKey, signatureBytes);
+    if (!ok) {
+        throw new IdentityCardInvalidError("This card's signature does not match its contents -- it may have been tampered with.");
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/identityShare.d.ts

@@ -0,0 +1,129 @@
+import type { IdentityDisclosure, SaltClient } from "./client";
+import { type CardSection } from "./identity.js";
+import type { AgentIdentity } from "./identities";
+import { type SaltId } from "./ids.js";
+/** Every SALT-IDENTITY-* marker starts with this -- webhook.ts checks it before attempting the more specific parse, the same way it gates on delegations.FLOOR_REQUEST_MARKER. */
+export declare const IDENTITY_MARKER_PREFIX = "[[SALT-IDENTITY-";
+export interface IdentitySlicePayload {
+    sections: CardSection[];
+    signature: string;
+}
+export type ParsedIdentityMarker = {
+    kind: "ask";
+    id: string;
+    keys: string[];
+    text?: string;
+} | {
+    kind: "slice";
+    id: string;
+    askId?: string;
+    payload: IdentitySlicePayload;
+} | {
+    kind: "decline";
+    id: string;
+    askId?: string;
+} | {
+    kind: "revoke";
+    id: string;
+};
+/**
+ * Parses one SALT-IDENTITY-* marker (plus, for SLICE, its JSON line) out of
+ * a decrypted plaintext. Returns null for anything that isn't one of these
+ * four markers, or that starts as one but is malformed (a bad id, an ASK
+ * with no keys, a SLICE whose JSON doesn't parse into {sections,
+ * signature}) -- webhook.ts treats either case as "starts with the prefix
+ * but nothing usable came out of it" and drops the message rather than
+ * guessing.
+ */
+export declare function parseIdentityMarker(plaintext: string): ParsedIdentityMarker | null;
+/** `[[SALT-IDENTITY-ASK id=… keys=k1,k2]]`, optionally followed by a text line. */
+export declare function formatIdentityAsk(id: string, keys: string[], text?: string): string;
+/** `[[SALT-IDENTITY-SLICE id=… [ask=…]]]` followed by the {sections, signature} JSON line. */
+export declare function formatIdentitySlice(id: string, sections: CardSection[], signature: string, askId?: string): string;
+/** `[[SALT-IDENTITY-DECLINE id=… [ask=…]]]`. */
+export declare function formatIdentityDecline(id: string, askId?: string): string;
+/** `[[SALT-IDENTITY-REVOKE id=…]]`. */
+export declare function formatIdentityRevoke(id: string): string;
+export interface IdentityAskInfo {
+    id: string;
+    keys: string[];
+    text?: string;
+    chatId: SaltId;
+    from: SaltId;
+}
+/**
+ * Handed to `onIdentityAsk`. Return the subset of `info.keys` to share
+ * (shares those, replying with a SLICE carrying `ask=info.id`) or
+ * `null`/`false` (sends a DECLINE carrying `ask=info.id`). Returning an
+ * empty array behaves like declining -- there is nothing to build a slice
+ * from. Leaving `onIdentityAsk` unset entirely means an incoming ask is
+ * never intercepted at all: it reaches `onMessage` as ordinary text with
+ * just the marker line stripped (see webhook.ts), unanswered.
+ */
+export type IdentityAskHandler = (info: IdentityAskInfo) => Promise<string[] | null | false | undefined> | string[] | null | false | undefined;
+export interface IdentitySliceEvent {
+    kind: "slice";
+    id: string;
+    askId?: string;
+    from: SaltId;
+    chatId: SaltId;
+    sections: CardSection[];
+    /** True only when the signature verified against the sender's own public key (fetched fresh from the chat's member list). False for a bad/missing signature, an unknown sender key, or a verification that itself failed -- never thrown. */
+    verified: boolean;
+}
+export interface IdentityDeclineEvent {
+    kind: "decline";
+    id: string;
+    askId?: string;
+    from: SaltId;
+    chatId: SaltId;
+}
+export interface IdentityRevokeEvent {
+    kind: "revoke";
+    id: string;
+    from: SaltId;
+    chatId: SaltId;
+}
+export type IdentitySharedEvent = IdentitySliceEvent | IdentityDeclineEvent | IdentityRevokeEvent;
+/** Handed every incoming SLICE, DECLINE and REVOKE from someone else -- never called for this identity's own outgoing messages. None of the three ever reach `onMessage`. */
+export type IdentitySharedHandler = (event: IdentitySharedEvent) => Promise<void> | void;
+export interface ShareOptions {
+    /** Set when this share answers an incoming SALT-IDENTITY-ASK -- rides on the SLICE marker as `ask=`. */
+    ask?: string;
+}
+export interface ShareResult {
+    /** Names the whole share -- what rides on the wire SLICE's `id=`, what every ledger row was posted under, and what `revoke(id)` takes to pull it all back at once. */
+    id: string;
+    messageId: SaltId;
+    /** Every non-observer chat member other than the caller this was disclosed to, in the same order client.getChatMembers returned -- one ledger row was written per entry, all under `id`. */
+    recipients: SaltId[];
+}
+export interface IdentitySharer {
+    /**
+     * Shares `keys` from this agent's own identity into `chatId`: ONE fresh
+     * id for the whole share, one ledger row posted under it per
+     * non-observer member other than the caller (salt-api keys a row on
+     * subject + recipient + id, so this is the same id every time; aborts
+     * on the first refusal with nothing sent), then ONE signed, encrypted
+     * SLICE message carrying that id to the whole chat, then a single
+     * message_id PATCH (every row shares the id, so one PATCH reaches all
+     * of them).
+     */
+    share(caller: AgentIdentity, chatId: SaltId, keys: string[], opts?: ShareOptions): Promise<ShareResult>;
+    /** Sends an ASK for `keys` into a 1:1 chat and returns its id. Refuses (before sending anything) outside a 1:1. */
+    ask(caller: AgentIdentity, chatId: SaltId, keys: string[], text?: string): Promise<string>;
+    /** Sends a bare DECLINE (optionally answering `askId`) with no ledger row -- there is nothing to disclose. Returns the decline message's own id. */
+    decline(caller: AgentIdentity, chatId: SaltId, askId?: string): Promise<{
+        id: string;
+    }>;
+    /** This agent's own disclosure ledger, newest first. */
+    disclosures(caller: AgentIdentity, opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<IdentityDisclosure[]>;
+    /** Revokes every ledger row under `id` (the id `share()` returned) in one call, then sends a REVOKE marker into the chat it was disclosed in. */
+    revoke(caller: AgentIdentity, id: string): Promise<IdentityDisclosure[]>;
+}
+/** Builds the {share, ask, decline, disclosures, revoke} surface bound to one client. */
+export declare function createIdentitySharer(client: SaltClient, pgpPassphrase: string): IdentitySharer;
+//# sourceMappingURL=identityShare.d.ts.map

package/dist/identityShare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identityShare.d.ts","sourceRoot":"","sources":["../src/identityShare.ts"],"names":[],"mappings":"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"}