@candledottv/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Candle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @candledottv/agent-sdk
+
+A typed TypeScript SDK for the Candle agent rail. It wraps the REST surface documented in
+`docs/headless-launch.md` (headless launches, jobs, dry runs, market state, quotes, feeds,
+verification, presets, agent profiles, image uploads), ships the webhook signature verifier,
+and drives the client-side HPKE seal behind linked-wallet import, so an agent integrates
+against typed methods instead of hand-rolled HTTP.
+
+Built on the global `fetch`; runs on Bun and Node 18+. Three runtime dependencies --
+`@hpke/core`, `@hpke/chacha20poly1305`, and `@scure/base` -- exist solely to power
+`importWallet()`'s client-side HPKE seal and base58 decode (see "Importing a wallet" below);
+nothing else in the SDK needs them. The one `node:` builtin used is `node:crypto` (webhook
+verification only), which Bun also provides. Edge runtimes without `node:crypto` would need a
+Web Crypto port of the verifier; that is a deliberate later concern.
+
+> **Not yet published to npm.** Publishing `@candledottv/agent-sdk` (and `@candledottv/mcp`)
+> is the post-Phase-2 follow-up. Until then, consume it as a workspace package:
+> `import { CandleClient } from "@candledottv/agent-sdk"`.
+
+## Quick start
+
+```ts
+import { CandleClient } from "@candledottv/agent-sdk"
+
+const candle = new CandleClient({
+  apiUrl: "https://api.alpha.candle.tv",
+  apiKey: process.env.CANDLE_AGENT_API_KEY, // cndl_live_... / cndl_test_...
+})
+
+// Public reads need no key.
+const market = await candle.getMarket("solana", "So11...mint")
+const quote = await candle.getQuote("solana", "So11...mint", { side: "buy", amountIn: "1000000000" })
+const feed = await candle.getFeed("new", "solana")
+const verdict = await candle.verify("hood", "0xToken")
+
+// Presets: fetch once, expand locally into a launch body.
+const presets = await candle.getPresets()
+const request = candle.expandPreset(presets, "solana-open-sol", {
+  name: "Trend Coin",
+  symbol: "TREND",
+  imageUrl: "https://example.com/logo.png",
+})
+```
+
+The API key is attached as `x-api-key` on every request when configured. The keyed methods
+(`launch`, `launchAsync`, `dryRunLaunch`, `getLaunchJob`, `reportActivity`, `uploadImage`)
+refuse to fetch without one and throw a plain `Error` locally instead of a server 401.
+
+## Launching with built-in idempotent retries
+
+`launch()` fills in a `clientLaunchId` (`"sdk-" + crypto.randomUUID()`) when you omit one, and
+retries transient failures by re-sending the SAME id, which the server's idempotency ledger
+resolves safely (no double mint, ever). Retries cover network errors, non-envelope 5xx
+responses, retryable 5xx envelopes, and the retryable in-flight 409; a non-retryable envelope
+(validation errors, an id reused with a different body, `LAUNCH_DISABLED`) is thrown
+immediately. Backoff is 250ms doubling per attempt, jittered, capped at 8s, bounded by
+`maxRetries` (default 3).
+
+```ts
+import { CandleApiError } from "@candledottv/agent-sdk"
+
+try {
+  const result = await candle.launch({
+    name: "Trend Coin",
+    symbol: "TREND",
+    imageUrl: "https://example.com/logo.png",
+    chain: "solana",
+    buyAmount: 100_000_000, // lamports
+  })
+  console.log("minted", result.mint, "explorer:", result.links.explorer)
+} catch (error) {
+  if (error instanceof CandleApiError) {
+    // Branch on code, never on message. error.status, error.retryable, error.field ride along.
+    console.error("launch failed:", error.code)
+  } else {
+    throw error
+  }
+}
+```
+
+Prefer not to block? `launchAsync()` sends `async: true`, returns the 202 body, and
+`waitForLaunch()` polls the jobs endpoint until the attempt is terminal:
+
+```ts
+const accepted = await candle.launchAsync({ name: "Trend Coin", symbol: "TREND", imageUrl: "https://..." })
+const job = await candle.waitForLaunch(accepted.clientLaunchId, { timeoutMs: 180_000, pollMs: 2_000 })
+if (job.status === "confirmed") console.log("minted", job.mint)
+else console.error("failed:", job.errorCode)
+```
+
+Need a hosted image first? `uploadImage(bytes, contentType)` posts raw bytes to
+`/api/v1/uploads/agent-image` and returns `{ imageUrl }`, ready for the launch body.
+
+## Importing a wallet
+
+`importWallet()` drives Candle's ciphertext-only wallet import end to end: it fetches Privy's
+HPKE receiver public key (`/wallets/import/init`), seals the private key locally with
+`encryptWalletKeyForImport()` (RFC 9180 Base mode, `DHKEM(P-256, HKDF-SHA256)` /
+`HKDF-SHA256` / `ChaCha20-Poly1305`), and submits only the resulting ciphertext and
+encapsulated key (`/wallets/import/submit`). **The plaintext private key never leaves the
+calling process, and Candle never receives, stores, or logs it at any point** -- the server is
+a ciphertext-only proxy to Privy's HPKE endpoint.
+
+```ts
+import { CandleClient, generateSignerKeypair } from "@candledottv/agent-sdk"
+
+const candle = new CandleClient({
+  apiUrl: "https://api.alpha.candle.tv",
+  apiKey: process.env.CANDLE_AGENT_API_KEY,
+})
+
+// A fresh P-256 (ECDSA) signer keypair. Only the public half ever leaves this process.
+const { privateKeyPem, publicKeyDerBase64 } = await generateSignerKeypair()
+// privateKeyPem is yours to store and sign with later; the SDK never transmits it anywhere.
+
+const result = await candle.importWallet({
+  chain: "solana", // or "evm"
+  address: "9xQe...wallet",
+  privateKey: existingWalletPrivateKey, // base58 for "solana", hex ("0x"-optional) for "evm"
+  signerPublicKey: publicKeyDerBase64,
+  label: "trading wallet",
+})
+console.log("linked", result.id, result.privyWalletId)
+```
+
+`generateSignerKeypair()` generates the signer Privy registers as the imported wallet's 1-of-1
+key quorum; `importWallet()` is the only place in this SDK that ever holds the wallet's
+plaintext private key, and only for the duration of the local HPKE seal.
+
+## Verifying webhooks
+
+Candle signs every webhook delivery with
+`x-candle-signature: t=<unix seconds>,v1=<hex hmac-sha256(secret, "<t>.<body>")>`. Verify the
+RAW request body string (do not re-serialize parsed JSON; key order changes break the digest):
+
+```ts
+import { verifyWebhookSignature } from "@candledottv/agent-sdk"
+
+// Example with a Bun/Node fetch-style handler:
+async function handleWebhook(req: Request): Promise<Response> {
+  const rawBody = await req.text()
+  const ok = verifyWebhookSignature(
+    process.env.CANDLE_WEBHOOK_SECRET ?? "",
+    req.headers.get("x-candle-signature"),
+    rawBody,
+    Math.floor(Date.now() / 1000),
+    300, // tolerance in seconds (default)
+  )
+  if (!ok) return new Response("invalid signature", { status: 401 })
+
+  const event = JSON.parse(rawBody)
+  // handle launch.confirmed, launch.failed, curve.graduated, migration.completed, migration.delayed
+  return new Response("ok")
+}
+```
+
+The verifier never throws: malformed headers, stale timestamps, wrong secrets, and tampered
+bodies all return `false`. Comparison is constant-time (`timingSafeEqual`).
+
+## Errors
+
+Every non-2xx response throws `CandleApiError` with `code`, `status`, `retryable`, and
+(for field-level validation) `field`. Structured envelopes map straight through; the few
+legacy endpoints without envelopes (activity, users) surface as `code: "HTTP_<status>"`.
+The full code table lives in `docs/headless-launch.md`.
+
+## Development
+
+```bash
+bun test          # pure tests against an injected fake fetch; no server, no network
+bun run typecheck # tsc --noEmit
+```

package/dist/authorization-signature.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Locally computes Privy's wallet-RPC "authorization signature" (Agent Pilot Phase 3, Task 2):
+ * the client half of the linked-wallet signing relay Task 1 built server-side
+ * (apps/api/src/routes/agent.ts's `POST /wallets/:id/sign`, and
+ * apps/api/src/services/privy-wallets.ts's `relaySignWithLinkedWallet`, which forwards this
+ * signature to Privy unchanged and MUST NEVER compute its own). An agent holds its own P-256
+ * signer key locally -- the private half of `generateSignerKeypair`'s output (wallet-import.ts)
+ * -- and must produce the SAME signature Privy's own SDK would produce for that key, over the
+ * SAME canonical request payload, WITHOUT the key ever leaving this process. That is the entire
+ * point of the relay.
+ *
+ * The reference implementation this must match is `generateAuthorizationSignature` from
+ * `@privy-io/server-auth/wallet-api` (installed at
+ * node_modules/@privy-io/server-auth/dist/esm/wallet-api/{index,utils}.mjs, v1.32.5, each
+ * minified to a single line, so described here by the compiled local variable names rather than
+ * source line numbers). Reading that source (not guessing) turned up three load-bearing details:
+ *
+ * 1. Canonicalization is RFC 8785 JSON Canonicalization Scheme (JCS), via the `canonicalize` npm
+ *    package -- utils.mjs's `y = e => Buffer.from(o(e))` where `o` is `canonicalize`'s default
+ *    export, called on `{version:1, method, url, body, headers}` (utils.mjs's `h`, exported as
+ *    `formatAuthorizationSignatureRequest`). JCS is NOT plain `JSON.stringify`: it sorts every
+ *    object's keys, recurses through arrays/nested objects, and has its own number-formatting and
+ *    undefined-skipping rules. Reimplementing JCS by hand risks a byte-level mismatch on some edge
+ *    case that would silently produce a signature Privy rejects. `canonicalize` is already a
+ *    transitive dependency of this monorepo's `@privy-io/server-auth` (the same situation
+ *    wallet-import.ts's module doc describes for the HPKE packages), so this module takes it as a
+ *    small, zero-dependency, real runtime dependency instead of hand-rolling JCS: it is the
+ *    literal function Privy's own SDK canonicalizes with, so using it is not a reimplementation
+ *    risk at all, unlike a from-scratch JCS implementation would be.
+ * 2. The signed message is SHA-256 of those canonical UTF-8 bytes, ECDSA/P-256 over that hash --
+ *    utils.mjs's `c = (e,r) => n.sign(a(e), r).toDERRawBytes()` (`n` = `@noble/curves/p256`, `a` =
+ *    `@noble/hashes/sha256`), called with `prehash` left at its default `false`, i.e. `a(e)` (the
+ *    SHA-256 hash) IS the "message" `n.sign` signs directly -- @noble's own `validateMsgAndHash`
+ *    only re-hashes when `prehash: true` is passed. `crypto.subtle.sign({name:"ECDSA",
+ *    hash:"SHA-256"}, ...)` computes that identical SHA-256-then-ECDSA-P-256 relationship, so
+ *    WebCrypto is a faithful stand-in for signing. It is NOT bit-identical: WebCrypto uses a
+ *    random per-signature nonce where @noble/curves' reference impl uses deterministic RFC 6979,
+ *    so the two will never produce the same signature bytes for the same input -- but both are
+ *    valid ECDSA signatures over the same (hash, key) pair, and verify identically against the
+ *    public key. This is exactly why this module's pinning test (authorization-signature.test.ts)
+ *    verifies signatures cryptographically rather than comparing signature strings.
+ * 3. Privy expects the signature DER-encoded (`.toDERRawBytes()`), base64-encoded, in the
+ *    `privy-authorization-signature` header. WebCrypto's ECDSA `sign` only ever produces the raw
+ *    IEEE P1363 format (a P-256 signature's 32-byte `r` immediately followed by its 32-byte `s`)
+ *    -- never DER -- so this module converts that raw signature to DER itself
+ *    (`rawEcdsaSignatureToDer`) before base64-encoding. Skipping this step would produce a
+ *    signature Privy's server does not recognize as valid, even though the same bytes verify fine
+ *    against the public key when treated as "raw".
+ *
+ * See authorization-signature.test.ts for the pinning test: it feeds the SAME generated P-256 key
+ * to both this module (as the PEM `buildPrivyAuthorizationSignature` takes) and the reference
+ * `generateAuthorizationSignature` (as `"wallet-auth:" + base64(pkcs8 DER)`, the form Privy's own
+ * key-normalization expects -- see `normalizeP256PrivateKeyToScalar` in utils.mjs, which strips
+ * that prefix and base64-decodes back to the same PKCS8 DER bytes `pemToPkcs8Bytes` extracts from
+ * the PEM here), then verifies BOTH resulting signatures cryptographically against the same
+ * public key (never compares the signature strings -- see point 2 above) and separately asserts
+ * the exact canonical byte payload this module hashes is identical to the reference's own
+ * `formatRequestForAuthorizationSignature` output for the same input.
+ */
+export interface BuildPrivyAuthorizationSignatureParams {
+    /** PKCS8 PEM private key for the agent's P-256 signer, as produced by `generateSignerKeypair` (wallet-import.ts). */
+    privateKeyPem: string;
+    /** The Privy wallet this signature authorizes an RPC call against; becomes the URL path segment. */
+    privyWalletId: string;
+    /** Privy's app id: sent as the `privy-app-id` header and folded into the canonical payload. */
+    appId: string;
+    /** The exact RPC request body being authorized. Must be byte-identical to what is actually sent -- see module doc, point 1. */
+    body: unknown;
+}
+/**
+ * The exact UTF-8 bytes this module hashes and signs: RFC 8785 JCS canonicalization of
+ * `{version, method, url, body, headers}`, matching Privy's own
+ * `formatRequestForAuthorizationSignature` byte-for-byte (both call the same `canonicalize`
+ * function -- see module doc, point 1). Exported so the pinning test can assert this equals the
+ * reference's own output, independently of whether the resulting signatures verify.
+ */
+export declare function canonicalAuthorizationPayloadBytes(params: Omit<BuildPrivyAuthorizationSignatureParams, "privateKeyPem">): Uint8Array;
+/** Strips PEM armor (BEGIN/END lines and newlines) and returns the raw PKCS8 DER bytes underneath, for WebCrypto's `importKey("pkcs8", ...)`. */
+export declare function pemToPkcs8Bytes(pem: string): Uint8Array;
+/**
+ * Builds the `privy-authorization-signature` header value for a Privy wallet-RPC request,
+ * computed entirely locally from `privateKeyPem` -- the key never leaves this function call, and
+ * this module makes no network request of any kind. See this module's doc comment for how each
+ * step matches `@privy-io/server-auth/wallet-api`'s `generateAuthorizationSignature`.
+ */
+export declare function buildPrivyAuthorizationSignature(params: BuildPrivyAuthorizationSignatureParams): Promise<string>;
+//# sourceMappingURL=authorization-signature.d.ts.map

package/dist/authorization-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-signature.d.ts","sourceRoot":"","sources":["../src/authorization-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAOH,MAAM,WAAW,sCAAsC;IACrD,qHAAqH;IACrH,aAAa,EAAE,MAAM,CAAA;IACrB,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAA;IACrB,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;IACb,+HAA+H;IAC/H,IAAI,EAAE,OAAO,CAAA;CACd;AAuBD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,IAAI,CAAC,sCAAsC,EAAE,eAAe,CAAC,GACpE,UAAU,CAQZ;AAED,iJAAiJ;AACjJ,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOvD;AA6CD;;;;;GAKG;AACH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,sCAAsC,GAC7C,OAAO,CAAC,MAAM,CAAC,CAMjB"}