@ssheleg/sheleg-dev 0.6.0 → 0.8.0

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/reference-emitter.mjs

@@ -0,0 +1,129 @@
+// A purchase emitter that satisfies the deduplication contract this skill states, and the
+// same emitter with one rule removed at a time.
+//
+// Two call sites, and which one may report a purchase is the whole invariant:
+//
+//   onChargeCleared(purchase)  <- the webhook handler, the only place that knows the money
+//                                 moved. Sends the Conversions API event.
+//   onThankYouPage(purchase)   <- the browser. Fires the pixel with the id the server will
+//                                 reuse, and reports nothing on its own authority.
+//
+// `without: ['shared-event-id']` and friends delete the lines a generated integration
+// routinely omits; `fixtures/README.md` shows the code each flag removes. Nothing here
+// reaches the network — the sink collects what WOULD have been sent, which is what the
+// assertions read. No access token appears in this directory at all.
+
+export const RULES = Object.freeze([
+  'shared-event-id',
+  'exact-event-name',
+  'webhook-sourced',
+  'keep-browser-event',
+  'hashed-identifiers',
+]);
+
+/** Meta compares `event_name` as well as the id, and it is the half that gets missed. */
+export const EVENT_NAME = 'Purchase';
+
+export function createSink() {
+  return { pixel: [], capi: [] };
+}
+
+function customData(purchase) {
+  return {
+    value: purchase.value,
+    currency: purchase.currency,
+    content_ids: purchase.contentIds,
+    content_type: 'product',
+    num_items: purchase.numItems,
+  };
+}
+
+export function createEmitter(sink, options = {}) {
+  const without = new Set(options.without || []);
+  for (const rule of without) {
+    if (!RULES.includes(rule)) throw new Error(`unknown rule: ${rule}`);
+  }
+  const has = (rule) => !without.has(rule);
+  let generated = 0;
+
+  /** One id, generated once at session creation, carried by both sides. */
+  function eventIdFor(purchase) {
+    if (has('shared-event-id')) return purchase.conversionEventId;
+    generated += 1;
+    return `evtid_generated_at_emission_${generated}`;
+  }
+
+  function eventNameFor(side) {
+    if (has('exact-event-name')) return EVENT_NAME;
+    // The trap: an id that matches and a name that does not deduplicates nothing.
+    return side === 'server' ? EVENT_NAME.toLowerCase() : EVENT_NAME;
+  }
+
+  function userData(purchase) {
+    const identifiers = has('hashed-identifiers')
+      ? { em: [purchase.emailSha256], external_id: [purchase.externalId] }
+      : { em: [purchase.email], external_id: [purchase.externalId] };
+    return {
+      ...identifiers,
+      client_ip_address: purchase.clientIpAddress,
+      client_user_agent: purchase.clientUserAgent,
+      fbp: purchase.fbp,
+      fbc: purchase.fbc,
+    };
+  }
+
+  function capiBody(purchase) {
+    return {
+      data: [{
+        event_name: eventNameFor('server'),
+        event_time: purchase.eventTime,
+        event_id: eventIdFor(purchase),
+        event_source_url: purchase.eventSourceUrl,
+        action_source: 'website',
+        user_data: userData(purchase),
+        custom_data: customData(purchase),
+      }],
+    };
+  }
+
+  return {
+    /** The webhook handler. `cleared` is the provider's word, not the browser's. */
+    onChargeCleared(purchase) {
+      if (purchase.cleared !== true) {
+        // Reached only by a caller that guessed. The gate below is the one that matters.
+        return { sent: false, why: 'the charge has not cleared' };
+      }
+      sink.capi.push(capiBody(purchase));
+      return { sent: true };
+    },
+
+    /**
+     * The thank-you page. It fires the pixel and NOTHING ELSE: a browser cannot know
+     * whether the charge cleared, and for an async method it usually has not.
+     */
+    onThankYouPage(purchase) {
+      if (!has('webhook-sourced')) {
+        // The defect: reporting the purchase from the one place with no idea whether the
+        // money moved. `purchase-capi-from-thank-you-page.json` is what this sends.
+        sink.capi.push(capiBody(purchase));
+      }
+      if (has('webhook-sourced') && purchase.cleared !== true) {
+        // Not even the pixel: a Purchase fired here exists for every session that reached
+        // the page, including the ones that never paid.
+        return { fired: false, why: 'the charge has not cleared' };
+      }
+      if (!has('keep-browser-event')) {
+        // The other direction: dropping the browser event loses the click ids, the consent
+        // state and the session that only the browser carries.
+        return { fired: false, why: 'browser event removed' };
+      }
+      sink.pixel.push([
+        'track',
+        eventNameFor('browser'),
+        customData(purchase),
+        { eventID: eventIdFor(purchase) },
+      ]);
+      return { fired: true };
+    },
+  };
+}

package/plugins/sheleg-dev/skills/ad-tracking/references/meta-linkedin.md

@@ -100,7 +100,14 @@ export function setFbAdvancedMatching(data: { em?: string; fn?: string }) {
 Advanced Matching is the one place a tracking integration can breach Meta's terms
 by accident, because the wrapper accepts whatever you hand it and hashes it
 without judgement. SHA-256 does **not** make a value safe to send: hashing is a
-matching mechanism, not a permission.
+matching mechanism, not a permission. That the wrapper receives a hash at all is checkable:
+`identifiers-reach-the-server-hashed` in `fixtures/assert-dedup-contract.mjs` requires every
+`user_data.em` entry to be 64 hex characters and refuses anything with an `@` in it. **Both
+halves are separately watched failing**, which they were not until 2026-08-20: the pack's
+`--self-test` measured one row per invariant, so the `@` guard could be neutered while the
+hex-shape assertion above it kept the invariant red, and this paragraph advertised a control
+nothing had ever seen fail. The matrix is now per call site. What may be hashed in the first
+place is the table below, and no assertion decides it.
 
 Meta's Business Tools Terms prohibit sharing data that "includes or is based on"
 any of these, and the prohibition covers the Pixel, the Conversions API, the
@@ -184,6 +191,15 @@ the server event usually arrives first, and this method then does nothing. Use
 Neither method deduplicates within a single source: two pixel fires of the same
 purchase are two conversions no matter what.
 
+**Proved, not asserted.** `fixtures/purchase-pixel-browser.json` and
+`fixtures/purchase-capi-server.json` are the two payloads one purchase produces, and
+`fixtures/assert-dedup-contract.mjs` compares them: `pixel-and-capi-carry-one-event-name`
+fails an emitter that sends `Purchase` from the browser and a lowercased variant from the
+server, which is the half of this contract that gets missed. The shape itself is a ratchet —
+`the-shipped-capi-fixture-is-what-a-correct-emitter-sends` requires the emitted body to equal
+the fixture byte for byte, so **the fixtures are the reference output rather than an
+illustration**.
+
 Source: [Deduplicate pixel and Conversions API
 events](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events),
 read 2026-08-16.

package/plugins/sheleg-dev/skills/crypto-payments/SKILL.md

@@ -39,14 +39,13 @@ and anything else that issues an invoice and calls you back.
 - [Status mapping — and finality](#status-mapping--and-finality)
 - [Webhook signature verification](#webhook-signature-verification)
 - [Idempotent webhook processing](#idempotent-webhook-processing)
-- [IP allowlisting behind a proxy](#ip-allowlisting-behind-a-proxy)
-- [CSRF exemption for callback routes](#csrf-exemption-for-callback-routes)
+- [Callback route hardening](#callback-route-hardening)
 - [The conversion buffer](#the-conversion-buffer)
 - [Reconciliation fields](#reconciliation-fields)
 - [Crediting: the amount waterfall](#crediting-the-amount-waterfall)
 - [Refunds and AML holds](#refunds-and-aml-holds)
-- [Local development](#local-development)
-- [Test matrix](#test-matrix)
+- [The test/live credential boundary](#the-testlive-credential-boundary)
+- [Local development and the test matrix](#local-development-and-the-test-matrix)
 - [Security checklist](#security-checklist)
 - [Common pitfalls](#common-pitfalls)
 
@@ -191,46 +190,17 @@ the read.
 
 ---
 
-## IP allowlisting behind a proxy
+## Callback route hardening
 
-Signature verification is the real gate; the allowlist is defence in depth and
-cheap. It is also the single most common cause of "webhooks stopped working
-after we moved to a load balancer".
+Two things about the *request* rather than about the money in it, and each one is the
+usual cause of "webhooks stopped working after we moved to a load balancer": reading the
+caller IP from the proxy hop you actually own instead of `x-forwarded-for[0]`, and
+exempting the **one** callback path from CSRF by exact match rather than by prefix — a
+prefix on `/api/payments` exempts the checkout endpoint too, which is where the money is.
 
-```ts
-function callerIp(req): string | null {
-  // Trust ONLY the hop your own infrastructure appends.
-  const xff = req.headers['x-forwarded-for'];
-  if (typeof xff === 'string') {
-    const hops = xff.split(',').map((s) => s.trim());
-    return hops[hops.length - TRUSTED_PROXY_COUNT] ?? null;
-  }
-  return req.socket.remoteAddress ?? null;
-}
-```
-
-Taking `xff[0]` trusts a header the client controls — anyone can claim to be the
-gateway. Count from the right by the number of proxies you actually run, and
-keep that number in configuration, because it changes when infrastructure does.
-
-Allowlist the provider's published callback IPs, log a rejection with the
-observed IP, and **never** fall back to "allow if the header is missing".
-
----
-
-## CSRF exemption for callback routes
-
-A gateway cannot present your CSRF token. Exempt the callback path explicitly
-and narrowly:
-
-```ts
-// middleware.ts (Next.js)
-export const config = { matcher: ['/((?!api/payments/webhook).*)'] };
-```
-
-Exempt the **one** path, by exact match, and make it the only route in your app
-that skips CSRF. A prefix match on `/api/payments` exempts the checkout endpoint
-too, which is where the money is.
+Both, with the code:
+[`references/callback-route-hardening.md`](references/callback-route-hardening.md).
+Signature verification above is the real gate; these are defence in depth.
 
 ---
 
@@ -309,47 +279,77 @@ Crypto has no chargeback, which people mistake for "no reversals".
 - **Never auto-refund from the webhook.** Route holds and refunds to a queue a
   human can see.
 
----
-
-## Local development
-
-Two paths, and you want both:
-
-**Skip the gateway.** A `SKIP_BILLING=true` branch that credits immediately and
-logs loudly. Everyone building a feature that merely *touches* checkout should
-use this. Make it impossible in production: assert `NODE_ENV !== 'production'`
-at the branch, not just in config.
+**And make it a precondition, not a paragraph.** The three lines above were advice for
+four releases: an agent that never read them, and a shell nobody read, were unaffected by
+all three. This pack now ships a `PreToolUse` gate —
+`plugins/sheleg-dev/hooks/money-gate.js` — that refuses a refund, a payout, closing a
+dispute, an export of `HELEKET_API_KEY` in a run declaring `test`, a live `sk_live_…` key
+and `SKIP_BILLING=true` in production, until the authorised person has signed that
+category off for the session. The pack's `README.md` carries the categories and how one is
+authorised. In your application the same rule is a queue and a human; in the agent's
+shell it is the hook.
 
-**Real gateway, tunnelled callback.** Callbacks cannot reach `localhost`:
-
-```bash
-cloudflared tunnel --url http://localhost:3000
-# → https://random-name.trycloudflare.com  →  set as the callback base URL, restart the app
-```
+---
 
-Then keep a **signed mock callback** in your test tooling — a script that builds
-a real payload, signs it with the dev key and POSTs it. This is what makes the
-sad paths (`wrong_amount`, `refund_fail`, `locked`) testable at all; you cannot
-ask a gateway to underpay you on demand.
+## The test/live credential boundary
+
+**Establish what the provider actually offers before designing around it.** Card
+processors hand you two parallel worlds — Stripe gives a whole second account and stamps
+the environment into the key itself (`sk_test_` / `sk_live_`). Most crypto gateways do
+not. Answer these three, from the provider's documentation, and write the answers down:
+
+1. **Is there a separate test credential?** Not "a test mode" — a *different secret*.
+2. **Can the environment be read from the key?** A prefix, a scope, anything.
+3. **Does the key also sign webhooks?** If yes, it cannot be scoped down: everything that
+   verifies a callback can also create a charge.
+
+The answers decide the design, and the worst combination is common: one key, no marker,
+"test mode" as a **toggle on the merchant account**. Then the same secret creates play
+invoices before somebody moves a dashboard switch and real ones after — with no deploy and
+no signal to any machine holding it.
+
+**Build the strongest control the provider allows, in this order:**
+
+1. **A separate sandbox account**, so the credential on a dev machine *cannot* reach
+   production. This is the only control that still works after everyone has forgotten why
+   it is there — which is the whole argument for preferring it to a warning in a README.
+2. **A declared environment plus a boot assertion**, when there is no second credential.
+   Keep the declaration in a variable **separate from the secret** (`<PROVIDER>_ENV=test|
+   production`): one variable that both carries the key and names its environment cannot
+   be checked against itself, two can. Pin the production identity with something
+   non-secret — the merchant id, or a truncated hash of the live key — and refuse
+   **both** mismatches at **startup**:
+
+   - a live credential declared test — the obvious loss;
+   - a test credential declared live — the quiet one, where invoices settle to a merchant
+     nobody reconciles and nothing errors until revenue is missing.
+
+   Assert at module load, not in the payment handler: a run that merely *holds* the key
+   must fail too, and it is agent and CI runs that hold keys without ever charging
+   anything. And when the check cannot tell — nothing pinned — refuse on the test side.
+   "Could not prove it was safe" must never read as "it was safe".
+3. **Write down what is left.** Where the provider offers no test credential, a developer
+   holds a production one and the assertion narrows that window without closing it. An
+   unavoidable exposure that is named is a different object from one that is silent: the
+   first gets rotated, monitored and revisited, the second gets rediscovered by an
+   incident.
+
+The same rule applies to the mock path below: `SKIP_BILLING=true` in production is not a
+shortcut, it is a free-money path, and the assertion is what refuses it.
+
+Worked end to end for one gateway with no test credential at all —
+[`references/heleket-provider.md`](references/heleket-provider.md), *The test/live
+boundary* and *Residual exposure*.
 
 ---
 
-## Test matrix
+## Local development and the test matrix
 
-Cover these, and plant a defect against each before believing the green:
-
-| Case | What it catches |
-|---|---|
-| valid signature | the happy path |
-| tampered signature | constant-time compare, 403 not 500 |
-| signature over a payload containing a URL | the escaping trap |
-| duplicate delivery of a settling status | idempotency guard |
-| `paid_over` | crediting the received amount, not the invoiced |
-| `wrong_amount` | no full credit on a partial payment |
-| out-of-order delivery (final, then earlier) | the `notIn` guard, not timestamps |
-| callback from a non-allowlisted IP | proxy-aware extraction |
-| `refund_process` then `refund_fail` | refund is a state machine |
-| `locked` | no credit, no auto-cancel |
+Two development paths you want both of — a `SKIP_BILLING=true` branch that is impossible
+in production, and a real gateway behind a tunnel with a signed mock callback for the sad
+paths a provider will not produce on demand — plus the ten cases to cover before believing
+a green suite, each with the defect it catches:
+[`references/testing-and-local-dev.md`](references/testing-and-local-dev.md).
 
 ---
 
@@ -363,6 +363,9 @@ Cover these, and plant a defect against each before believing the green:
 - [ ] CSRF exempted for exactly one path, by exact match
 - [ ] Entitlement never granted from a client-side redirect
 - [ ] API key and merchant id from environment, never in the repository
+- [ ] A sandbox account is used where the provider offers one, or the reason it cannot be is written down
+- [ ] The declared environment is a variable separate from the secret, and a boot assertion refuses **both** mismatches
+- [ ] The assertion runs at module load, so a run that only holds the key fails too
 - [ ] Callback URL is HTTPS in every environment that is not a local tunnel
 - [ ] `SKIP_BILLING` asserted impossible in production
 - [ ] Reconciliation fields written at settlement time
@@ -382,3 +385,5 @@ Cover these, and plant a defect against each before believing the green:
 | "Paid" users with no product | credited from the browser redirect |
 | Half the payments land as `wrong_amount` | no conversion buffer |
 | Cannot answer "how much did we net" | commission and `merchantAmount` never stored |
+| A dev machine, a CI job or an agent run is holding the production key | no separate credential, and no assertion binding the key to a declared environment |
+| Real invoices in a merchant dashboard nobody watches | a staging credential declared live — the mismatch nothing refused |

package/plugins/sheleg-dev/skills/crypto-payments/references/callback-route-hardening.md

@@ -0,0 +1,55 @@
+# Callback route hardening — the proxy hop and the CSRF hole
+
+Split out of `SKILL.md` on 2026-08-20, when its body measured ~4894 tokens against the
+house working limit of 4750. Both sections below are web plumbing rather than payment
+logic — they are about the request that carries a callback, not about the money in it —
+which is why they are the seam. Signature verification (`SKILL.md`, *Webhook signature
+verification*) is the real gate; these two are defence in depth, and each has a failure
+mode that looks like "webhooks stopped working" rather than like a security event.
+
+---
+
+## IP allowlisting behind a proxy
+
+Signature verification is the real gate; the allowlist is defence in depth and
+cheap. It is also the single most common cause of "webhooks stopped working
+after we moved to a load balancer".
+
+```ts
+function callerIp(req): string | null {
+  // Trust ONLY the hop your own infrastructure appends.
+  const xff = req.headers['x-forwarded-for'];
+  if (typeof xff === 'string') {
+    const hops = xff.split(',').map((s) => s.trim());
+    return hops[hops.length - TRUSTED_PROXY_COUNT] ?? null;
+  }
+  return req.socket.remoteAddress ?? null;
+}
+```
+
+Taking `xff[0]` trusts a header the client controls — anyone can claim to be the
+gateway. Count from the right by the number of proxies you actually run, and
+keep that number in configuration, because it changes when infrastructure does.
+
+Allowlist the provider's published callback IPs, log a rejection with the
+observed IP, and **never** fall back to "allow if the header is missing".
+
+## CSRF exemption for callback routes
+
+A gateway cannot present your CSRF token. Exempt the callback path explicitly
+and narrowly:
+
+```ts
+// middleware.ts (Next.js)
+export const config = { matcher: ['/((?!api/payments/webhook).*)'] };
+```
+
+Exempt the **one** path, by exact match, and make it the only route in your app
+that skips CSRF. A prefix match on `/api/payments` exempts the checkout endpoint
+too, which is where the money is.
+
+---
+
+Back to [`SKILL.md`](../SKILL.md) — *Webhook signature verification* is the gate these two
+sit behind, and *Test matrix* in
+[`testing-and-local-dev.md`](testing-and-local-dev.md) carries the non-allowlisted-IP case.