@chaindaddy/mcp 0.5.0 → 0.6.0

package/skills/sell-items-in-your-app/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sell-items-in-your-app
+description: Run a Chain Daddy creator store - open it, add items priced in a token or in dollars, create orders from your server, have the buyer's wallet pay, wait for confirmed, deliver, read and spend what a wallet owns, drops and rewards, webhooks, refunds - and test the whole loop on a no-money test store first. Use when someone wants to sell credits, skins, passes or badges for their token, give items away, or unlock perks for holders.
+license: MIT
+---
+
+# Sell items in your app
+
+A store sells **items** for one token. The buyer's wallet pays the token's payout wallet directly, in one
+on-chain transaction; the checkout contract has no owner and holds no balance. Once the payment confirms,
+Chain Daddy grants the item and signs a receipt. Items live off chain: they can't be transferred or cashed out.
+
+## Tools
+
+| Step | MCP (local server) | CLI (`npm i -g @chaindaddy/cli@beta`) | HTTP (`https://api.chaindaddy.io`) |
+|---|---|---|---|
+| Open the store | `iap_open_store` | `chaindaddy iap store open --chain base --crown 8` | `POST /api/v2/iap/stores` |
+| Test store | `iap_open_test_store` | `chaindaddy iap store test <storeId>` | `POST /api/v2/iap/stores/{id}/test-store` |
+| Items | `iap_create_sku`, `iap_update_sku`, `iap_list_skus` | `chaindaddy iap sku create/update/archive` | `/api/v2/iap/stores/{id}/skus` |
+| Server key | `iap_create_store_key` | `chaindaddy iap key create` | `POST /api/v2/iap/stores/{id}/keys` |
+| Orders | `iap_create_order`, `iap_get_order`, `iap_test_pay` | `chaindaddy iap order create/show/test-pay` | `POST /api/v2/iap/orders` |
+| What a wallet owns | `iap_get_entitlements`, `iap_consume`, `iap_grant`, `iap_revoke` | `chaindaddy iap entitlements/consume/grant/revoke` | `/api/v2/iap/stores/{id}/entitlements` |
+| Rewards | `iap_create_drop`, `iap_set_drop_status`, `iap_award` | `chaindaddy iap drop …` | `/api/v2/iap/stores/{id}/drops` |
+| Events | `iap_list_events`, `iap_set_webhook`, `iap_test_webhook` | `chaindaddy iap events/webhook …` | `/api/v2/iap/stores/{id}/events` |
+
+Credentials: account calls (open a store, manage items and keys) use the human's `chaindaddy login` on this
+computer (or a `cd_live_…` key in `CHAINDADDY_API_KEY` on a server). The game server uses a **store key** `cd_iap_…` from `CHAINDADDY_IAP_KEY`: one store,
+only its scopes, sent alone as `Authorization: Bearer`. The plan gate: Developer, Partner or Enterprise, or
+Developer Beta Program membership; otherwise every call answers `403 IAP_PLAN_REQUIRED` - stop and tell the human.
+
+## Steps
+
+1. **Open the store** with the token page's chain key and crown id. Opening again returns the same store.
+   Report `id`, `payoutAddress` (starts as the owner's wallet), and `feeBps` (0 on a token launched in a Chain
+   Daddy launchpad pool, 250 otherwise).
+2. **Add items.** New items are `draft`; set `status: "active"` to list one. Create reward-only items (no
+   price, like `credits`) before the bundles that `grants` them. Example credit pack:
+   ```json
+   { "sku": "credits.100", "type": "consumable", "name": "100 credits",
+     "priceUsdMicros": 5000000, "minPrice": "1000000000000000000000",
+     "grants": [{ "sku": "credits", "quantity": 100 }], "status": "active" }
+   ```
+   `sku`: lowercase letters, digits, `.`, `_`, `-`, up to 64. A fixed `price` is a **base-unit string**
+   (5,000 tokens at 18 decimals = `"5000000000000000000000"`). An item has `price` or `priceUsdMicros`, not
+   both. `currency` is `token` (default), `native` or `usdc`. Confirm human-readable amounts with the human.
+3. **Make a store key** with only the scopes the server needs, typically `orders:read orders:write
+   entitlements:read entitlements:write`. The secret is shown **once**: tell the human to store it as
+   `CHAINDADDY_IAP_KEY` in their secrets manager. Never print it back.
+4. **Test it** (next section) before any live sale.
+5. **Server creates the order** for the user's wallet, with `appAccountToken` = your own user id and an
+   `Idempotency-Key` per purchase attempt (your cart id). It locks the price for about 20 minutes (5 for a
+   dollar price paid in the token or coin).
+6. **Client pays** from the order's `payment` block, as given. EVM: send `calls.approve` (when present), wait
+   for it, then `calls.pay`; or sign `permitTypedData` and call `payWithPermit`. Solana: the wallet signs and
+   sends `payment.transaction`. The client never computes an amount.
+7. **Wait for `confirmed`.** Poll the order, or listen for `iap.order.confirmed`. Optionally
+   `POST /api/v2/iap/orders/{id}/submit` with `{"txHash": …}` to check at once.
+8. **Deliver.** Verify the receipt (`verify-receipts-and-sessions`), then grant; or read the item ledger and
+   spend with `consume` (with an idempotency key).
+
+On a token page, a Crown App skips steps 5-7: it declares `iap:purchase` and sends
+`onAction({ type: 'iap-purchase', sku, quantity })`; the page runs the sale (see `build-a-crown-app`).
+
+A Crown App can also spend the viewer's own consumable with no server: it declares `iap:consume` and sends
+`onAction({ type: 'iap-consume', sku, quantity, key })` from the viewer's tap. It works only for an item whose
+`maxAppSpend` the store's owner set (the most an app may spend per request; null means no app can), and it is
+never proof: a holder can make that spend without the app. Keep `maxAppSpend` null and spend with `consume`
+on your server for anything competitive or redeemed for a prize.
+
+## Test store first
+
+Available where `GET /api/v2/iap/config` answers `"testMode": true`.
+
+1. `iap_open_test_store` with the **live** store id. It copies the live catalog once; after that they are separate.
+2. `iap_create_store_key` on the **test** store id. Its secret starts `cd_iap_test_`.
+3. Create an order with the test key; its `payment` is `{"kind":"test"}`.
+4. `iap_test_pay` (`POST /api/v2/iap/orders/{id}/test-pay`): the order confirms through the real path. No
+   chain, no money, no fee.
+5. The receipt and webhooks carry `"livemode": false`. Give the test store its own webhook.
+6. Go live by switching to the live key. Token prizes and claim links don't run on a test store.
+
+## Rewards and webhooks
+
+- One-off gift: `iap_grant`. A drop: `iap_create_drop` with `mode` `claim` (a link), `push` (a wallet list),
+  or `award` (your server awards a wallet with `iap_award`, scope `rewards:award`). Drops start as drafts.
+- Webhook: `iap_set_webhook` with a public `https://` URL; the `whsec_…` secret is shown once. Check
+  `X-Webhook-Signature` (hex HMAC-SHA256 of the raw body) before parsing. Answer 2xx within 5 seconds.
+- Reconcile from the event feed (`iap_list_events` with `after` = your last event id). The webhook makes you
+  fast; the feed makes you complete.
+- Refunds: the creator sends the money back from their wallet, then records it with `iap_refund_order`
+  (`refund_tx_hash`; CLI `--tx`), which revokes the items and receipt. Chain Daddy cannot move a buyer's funds.
+
+## Mistakes to avoid
+
+- Granting on `paid`, or before verifying the receipt's signature, `storeId` and `livemode`.
+- A store key in the game client. Only the server holds it.
+- Retrying a write with a new idempotency key: it can sell or grant twice. Reuse the same key.
+- Editing the `payment` block, or paying in another currency: the payment is recorded as `order.mismatch`
+  and grants nothing.
+- Treating `503 PRICE_UNAVAILABLE` as a failure: the dollar price can't be converted right now; retry in a minute.
+- Items with a random outcome (loot boxes): not allowed. Never call items money or a balance.
+- Sending a payment for the human. They pay from their own wallet.
+
+## Docs
+
+- https://docs.chaindaddy.io/developer/store-and-rewards (every field, rule, event and limit)
+- https://docs.chaindaddy.io/developer/test-your-integration
+- OpenAPI: https://docs.chaindaddy.io/openapi.yaml, tag **Creator Store**

package/skills/sign-in-with-chain-daddy/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: sign-in-with-chain-daddy
+description: Add "Sign in with Chain Daddy" to a website, game or app - standard OpenID Connect (authorization code + PKCE, ES256 ID tokens) that tells your server which wallet the visitor controls. Covers registering a client, the stock-library setup, the claims to check, and how it differs from a Crown App session token. Use when someone wants wallet sign-in, "log in with Chain Daddy", or to link a player account to a wallet.
+license: MIT
+---
+
+# Sign in with Chain Daddy
+
+The visitor goes to chaindaddy.io, approves your site, and comes back with an ID token that says **which
+wallet they control**. It is standard OpenID Connect, so use a stock library (openid-client, Auth.js,
+go-oidc, Authlib, Spring Security, .NET). You get an ID token and nothing else: no refresh token, no access
+to the Chain Daddy API for the user, no email, no balance. Keep your own session afterwards.
+
+## Endpoints
+
+Use discovery: `https://api.chaindaddy.io/.well-known/openid-configuration`
+
+| | |
+|---|---|
+| Issuer | `https://api.chaindaddy.io` |
+| Authorize (consent page) | `https://chaindaddy.io/_oauth/authorize` |
+| Token | `https://api.chaindaddy.io/api/v2/oauth/token` |
+| Keys | `https://api.chaindaddy.io/api/v2/oauth/jwks` |
+
+## 1. Register a client (the human does this)
+
+Needs Developer Beta Program membership (free to register). Easiest: the developer portal,
+https://chaindaddy.io/_developer → **Sign-in** → **New client**. Or:
+
+```bash
+chaindaddy oauth client create --name "My Game" \
+  --redirect-uri https://example.com/auth/callback --confidential --crown base:8
+```
+
+API: `POST https://api.chaindaddy.io/api/v2/developer/oauth-clients` with the human's `cd_live_…` key.
+
+- `redirectUris` match **exactly**: no wildcards. `https` only, except `http://localhost` and
+  `http://127.0.0.1` for development.
+- `confidential: true` for a server that keeps a secret (`cd_oauth_…`, shown once - the human stores it).
+  A single-page app, game client or native app stays public and uses PKCE with no secret.
+- `name`: up to 40 characters, and may not contain "Chain Daddy", "official", "support" or "wallet".
+- `crown` (optional) earns the consent screen's **verified** mark when the human manages that token page
+  and the redirect host is one of the page's verified domains.
+
+## 2. Wire the flow
+
+Node, with openid-client:
+
+```ts
+import * as client from 'openid-client';
+
+const config = await client.discovery(
+  new URL('https://api.chaindaddy.io'), process.env.CD_CLIENT_ID!,
+  { id_token_signed_response_alg: 'ES256' },
+  client.ClientSecretPost(process.env.CD_CLIENT_SECRET!), // client.None() for a public client
+);
+
+// Sign-in: keep verifier, state and nonce in the visitor's session
+const verifier = client.randomPKCECodeVerifier();
+const state = client.randomState();
+const nonce = client.randomNonce();
+const url = client.buildAuthorizationUrl(config, {
+  redirect_uri: 'https://example.com/auth/callback', scope: 'openid wallets',
+  code_challenge: await client.calculatePKCECodeChallenge(verifier), code_challenge_method: 'S256',
+  state, nonce,
+});
+
+// Callback
+const tokens = await client.authorizationCodeGrant(config, new URL(req.url, 'https://example.com'), {
+  pkceCodeVerifier: verifier, expectedState: state, expectedNonce: nonce,
+});
+const claims = tokens.claims()!;
+if (claims.typ !== 'signin+v1') throw new Error('not a Chain Daddy sign-in');
+const wallet = claims.sub; // start your own session for this wallet
+```
+
+Auth.js: a provider with `type: 'oidc'`, `issuer: 'https://api.chaindaddy.io'`,
+`checks: ['pkce', 'state', 'nonce']`, `client: { id_token_signed_response_alg: 'ES256' }`, and a `profile()`
+that throws unless `typ === 'signin+v1'`.
+
+## Scopes and claims
+
+| Scope | Adds |
+|---|---|
+| `openid` (required) | `sub` (the wallet: lowercase hex on EVM, base58 on Solana), `chain` (`evm` or `solana`) |
+| `wallets` | `wallets`: every wallet linked to the account, `sub` first |
+| `profile` | `identity`: the handle they chose to publish |
+
+Check on every ID token: signature (ES256, keys above), `iss` = `https://api.chaindaddy.io`, `aud` = your
+client id, `typ` = `signin+v1`, `nonce` = the one you sent, `exp` (5 minutes).
+
+## After sign-in
+
+Gate on what the wallet owns live, on your server: your store's
+`GET /api/v2/iap/stores/{id}/entitlements?wallet=<sub>` (holder unlocks included). Never put a balance in
+your session: it goes stale in minutes.
+
+## Crown Apps use something else
+
+Inside a Crown App on a token page, use the `session-token` action (an `app-session+v1` token, EdDSA, keys
+at `/api/v2/apps/jwks`). If your site and your Crown App share a server, verify both kinds and key people by
+`sub`: it is the same wallet string in both. See `verify-receipts-and-sessions`.
+
+## Mistakes to avoid
+
+- Skipping PKCE (`S256`) or `state`: both are required on every request.
+- Not checking `typ`. A token of another kind must never pass for a sign-in.
+- Expecting a refresh token or API access: there is neither. A returning visitor who approved before signs
+  in again without a click.
+- Redirect URIs that differ by a slash or a port: they must match exactly, or chaindaddy.io refuses.
+- Putting the client secret in a browser, game client or repo.
+- Asking the visitor to sign a second login message in their wallet. This is the sign-in.
+
+## Docs
+
+https://docs.chaindaddy.io/developer/sign-in-with-chain-daddy

package/skills/verify-receipts-and-sessions/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: verify-receipts-and-sessions
+description: Verify what Chain Daddy signs on your own server before acting on it - store purchase receipts (iap-receipt+v1), Crown App session tokens (app-session+v1), Sign in with Chain Daddy ID tokens (signin+v1), and webhook signatures - with the exact keys, claims and checks, plus published test vectors. Use when writing server code that grants items, credits a purchase, trusts a player's wallet, or receives Chain Daddy webhooks.
+license: MIT
+---
+
+# Verify receipts, sessions and webhooks
+
+Never act on something because a client sent it. Each kind below has its own keys and its own `typ` claim,
+so one can never pass for another - as long as you check `typ`.
+
+## Which token is which
+
+| You have | `typ` claim | Algorithm | `iss` | Keys (JWKS) | Also check |
+|---|---|---|---|---|---|
+| Store receipt (a confirmed purchase) | `iap-receipt+v1` | EdDSA (Ed25519) | `https://chaindaddy.io` | `https://api.chaindaddy.io/api/v2/iap/jwks` | `storeId` is your store; `livemode` is `true` in production; credit each `orderId` once |
+| Crown App session token (`session-token` action) | `app-session+v1` | EdDSA | `https://chaindaddy.io` | `https://api.chaindaddy.io/api/v2/apps/jwks` | `aud` is your app id (`<developerId>/<name>`); `exp` (5 min, allow 30 s skew); refuse a `jti` you have seen; `idv === true` if you need a verified person |
+| Sign in with Chain Daddy ID token | `signin+v1` | ES256 | `https://api.chaindaddy.io` | `https://api.chaindaddy.io/api/v2/oauth/jwks` | `aud` is your client id; `nonce`; `exp` (5 min) |
+
+Notes:
+- The JWS **header** `typ` is a plain `JWT`. What the token is lives in the `typ` **claim**. Check the claim.
+- Pick the key by the header's `kid`. Each set lists the current key first and keeps the previous one, so a
+  cached remote key set that refetches on an unknown `kid` survives rotation with no work.
+- `sub` is the wallet in all three: lowercase `0x…` on EVM, base58 on Solana.
+
+## TypeScript (jose)
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const API = 'https://api.chaindaddy.io';
+const ISSUER = 'https://chaindaddy.io';
+const receiptKeys = createRemoteJWKSet(new URL('/api/v2/iap/jwks', API));
+const sessionKeys = createRemoteJWKSet(new URL('/api/v2/apps/jwks', API));
+
+export async function verifyReceipt(jws: string, storeId: string) {
+  const { payload } = await jwtVerify(jws, receiptKeys, { algorithms: ['EdDSA'], issuer: ISSUER });
+  if (payload.typ !== 'iap-receipt+v1') throw new Error('not a store receipt');
+  if (payload.storeId !== storeId) throw new Error('receipt is for another store');
+  if (payload.livemode === false && process.env.NODE_ENV === 'production') throw new Error('test receipt');
+  return payload; // grant by payload.sku, payload.quantity, payload.wallet; dedupe on payload.orderId
+}
+
+export async function verifySession(token: string, appId: string) {
+  const { payload } = await jwtVerify(token, sessionKeys, {
+    algorithms: ['EdDSA'], issuer: ISSUER, audience: appId, clockTolerance: 30,
+  });
+  if (payload.typ !== 'app-session+v1') throw new Error('not an app session token');
+  if (!payload.exp) throw new Error('no expiry');
+  return payload; // payload.sub is the wallet; check payload.idv === true to require a verified person
+}
+```
+
+For the ID token, use your OpenID Connect library (see `sign-in-with-chain-daddy`), or `jwtVerify` with the
+oauth key set, `issuer: 'https://api.chaindaddy.io'`, `audience: <client id>`, `algorithms: ['ES256']`, then
+check `typ === 'signin+v1'` and the nonce. Go: `server/cdapi` in https://gitlab.com/opencrown/flux-gp-kit.
+
+## Refunds: offline is not enough for everything
+
+An offline receipt check can't see a refund made since. For anything that matters after the fact, also check
+online - `POST https://api.chaindaddy.io/api/v2/iap/receipts/verify` with `{"receipt": "…"}` returns
+`valid` or `revoked` - or read the store's item ledger (`GET …/entitlements?wallet=`), which is the source of
+truth for what a wallet owns now.
+
+## Webhook signatures
+
+| Webhook | Header | How to check |
+|---|---|---|
+| Store webhook (`iap.*`) | `X-Webhook-Signature` | Hex HMAC-SHA256 of the **raw body**, keyed with the `whsec_…` secret as given |
+| Crown App runner events | `X-App-Signature` | Hex HMAC-SHA256 of the raw body, keyed with the runner secret **hex-decoded to bytes** |
+
+```js
+import crypto from 'node:crypto';
+function verifyStoreWebhook(rawBody, signature, secret) {
+  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  return signature?.length === expected.length &&
+    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+Check against the raw bytes before parsing JSON, compare in constant time, and ignore a repeated event `id`
+(retries reuse it). Answer 2xx within 5 seconds.
+
+## Prove your checker with the test vectors
+
+https://docs.chaindaddy.io/vectors/tokens.json holds two key sets (`jwks.session`, `jwks.receipts`), a fixed
+`now`, an `appId`, a `storeId` and 15 tokens marked `valid` or not (expired, clock skew, another app, another
+issuer, `typ` only in the header, no expiry, a forgery, a receipt offered as a session and the reverse,
+another store). Load the sets with `createLocalJWKSet`, run every case at `now`, and pass only when your
+code accepts exactly the valid ones. Add this as a unit test.
+
+## Mistakes to avoid
+
+- Checking the header `typ` instead of the claim, or not checking `typ` at all.
+- Verifying a session token against the receipt keys, or the other way round: they use different key sets.
+- Using `iss: https://api.chaindaddy.io` for receipts and sessions. Only Sign in ID tokens use the `api.` issuer.
+- Accepting a test receipt (`livemode: false`) or another store's receipt in production.
+- Crediting the same `orderId` twice when the webhook and your poller both see it.
+- Parsing the webhook body before checking its signature, or comparing with `===`.
+- Treating a session token as API access: it only proves presence to your server.
+
+## Docs
+
+- https://docs.chaindaddy.io/developer/verifying-tokens
+- https://docs.chaindaddy.io/developer/store-and-rewards#verifying-receipts-on-your-server
+- https://docs.chaindaddy.io/developer/security#session-tokens