perly-pay 0.1.0 → 0.1.1

package/README.md

@@ -198,7 +198,7 @@ Add your site's origin under Dashboard → Settings → Checkout so the checkout
 
 - Docs: <https://pay.perly.io/docs> · API reference: <https://pay.perly.io/docs/api> · SDKs: <https://pay.perly.io/docs/sdks>
 - OpenAPI: <https://pay.perly.io/api/v1/openapi.json>
-- PHP: [`perly/perly-pay`](https://pay.perly.io/docs/sdks) on Composer, the same calls and the same webhook check
+- PHP: [`perly/perly-pay`](https://pay.perly.io/docs/sdks), the same calls and the same webhook check, is not on Packagist yet; until then PHP calls the API directly, and `npx perly-pay init` in a Laravel project writes files that do (Laravel's HTTP client and the signature check written out)
 
 ## Build
 

package/dist/cli/detect.js

@@ -152,10 +152,15 @@ export function detectProject(dir, forced) {
         notes,
     };
 }
+/**
+ * What to run to install the SDK, or null when there is nothing to: the
+ * Laravel files call the API with Laravel's own HTTP client and check the
+ * signature themselves, since perly/perly-pay is not on Packagist yet.
+ */
 export function installCommand(project) {
     switch (project.packageManager) {
         case "composer":
-            return "composer require perly/perly-pay";
+            return null;
         case "pnpm":
             return "pnpm add perly-pay";
         case "yarn":

package/dist/cli/env.js

@@ -6,6 +6,30 @@ export const KEY_VAR = "PERLY_PAY_SECRET_KEY";
 export const WEBHOOK_SECRET_VAR = "PERLY_PAY_WEBHOOK_SECRET";
 export const API_VAR = "PERLY_PAY_API";
 export const DEFAULT_API = "https://pay.perly.io";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * `--api` as an origin, or null. https, or plain http only to this machine
+ * (as perly-pay-mcp's PERLY_PAY_API): init sends the key there, and a key
+ * never crosses a network unencrypted. No user name, path, query or fragment,
+ * so `https://pay.perly.io@evil.example` cannot pass for Perly Pay.
+ */
+export function checkApiOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim().replace(/\/+$/, ""));
+    }
+    catch {
+        return null;
+    }
+    if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
+        return null;
+    if (/[@?#\\]/.test(raw.trim().replace(/^https?:\/\//i, "")))
+        return null;
+    const local = LOCAL_HOSTS.has(url.hostname) || url.hostname.endsWith(".localhost");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local))
+        return null;
+    return url.origin;
+}
 const line = (name) => new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=(.*)$`, "m");
 /** A variable's value in a dotenv file ("" when set empty), or null when absent. Quotes and a trailing comment are dropped. */
 export function readEnvValue(content, name) {

package/dist/cli/init.js

@@ -6,12 +6,13 @@
  * Everything outside the disk goes through `InitIO`, so the tests drive
  * it without a terminal, a browser or a network.
  */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
 import { PerlyPay } from "../index.js";
 import { PerlyPayError } from "../errors.js";
 import { DetectError, FRAMEWORK_NAMES, detectProject, installCommand } from "./detect.js";
-import { API_VAR, DEFAULT_API, KEY_VAR, WEBHOOK_SECRET_VAR, checkTestKey, ensureIgnored, maskKey, readEnvValue, upsertEnv, } from "./env.js";
+import { API_VAR, DEFAULT_API, KEY_VAR, WEBHOOK_SECRET_VAR, checkApiOrigin, checkTestKey, ensureIgnored, maskKey, readEnvValue, upsertEnv, } from "./env.js";
 import { DEFAULT_OFFER, planFiles } from "./templates.js";
 /** The Claude Code plugin and the MCP server, as their packages are named. */
 export const PLUGIN_NAME = "perly-pay";
@@ -75,6 +76,47 @@ async function registerWebhook(url, key, api, io, haveSecret) {
     const made = await pay.webhookEndpoints.create({ url, enabled_events: ["invoice.fulfilled"], description: "npx perly-pay init" });
     return { endpoint: made.id, secret: made.secret ?? null, how: "created" };
 }
+/** Whether git tracks the file: `git ls-files --error-unmatch` (no shell). Outside a repository, or without git, it does not. */
+export function trackedByGit(dir, path) {
+    try {
+        return spawnSync("git", ["ls-files", "--error-unmatch", "--", path], { cwd: dir, stdio: "ignore", timeout: 10_000 }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why init must not write `rel` in `root`, or null: it is a symbolic link, or a
+ * linked folder above it leads out of the project. init writes only real files
+ * inside the project, so a cloned repository's links cannot aim it elsewhere.
+ */
+function unsafeTarget(root, rel) {
+    const target = join(root, rel);
+    try {
+        if (lstatSync(target).isSymbolicLink())
+            return `${rel} is a symbolic link`;
+    }
+    catch {
+        // Not there yet: its folder decides.
+    }
+    let rootReal;
+    try {
+        rootReal = realpathSync(root);
+    }
+    catch {
+        return null;
+    }
+    for (let dir = dirname(target);; dir = dirname(dir)) {
+        try {
+            const real = realpathSync(dir);
+            return real === rootReal || real.startsWith(rootReal + sep) ? null : `${rel} would land outside the project, through a linked folder`;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                return null;
+        }
+    }
+}
 function language(project) {
     return project.framework === "laravel" ? "php" : project.style === "ts" ? "typescript" : "javascript";
 }
@@ -99,9 +141,9 @@ export async function init(options, io) {
     return result;
 }
 async function run(options, io, result) {
-    const api = (options.api ?? DEFAULT_API).replace(/\/+$/, "");
-    if (!/^https?:\/\/[^/]+$/.test(api))
-        throw new InitError(`--api takes an origin, like ${DEFAULT_API} or http://localhost:3200.`);
+    const api = checkApiOrigin(options.api ?? DEFAULT_API);
+    if (!api)
+        throw new InitError(`--api takes an origin, like ${DEFAULT_API}: https, or plain http only for localhost (http://localhost:3200). The key is sent there.`);
     const developersUrl = `${api}/dashboard/developers`;
     const offer = options.offer ?? DEFAULT_OFFER;
     const project = detectProject(options.dir, options.framework);
@@ -116,6 +158,24 @@ async function run(options, io, result) {
     const envText = readText(envPath) ?? "";
     const { key, source } = await resolveKey(options, io, envText, developersUrl);
     result.key = key ? "set" : "placeholder";
+    // Nothing written yet: refuse a target that is a link, or a keys file git would commit.
+    const unsafe = [
+        project.envFile,
+        ".gitignore",
+        ...plan.files.filter((f) => options.force || readText(join(project.dir, f.path)) === null).map((f) => f.path),
+    ]
+        .map((rel) => unsafeTarget(project.dir, rel))
+        .filter((why) => why !== null);
+    if (unsafe.length) {
+        throw new InitError(`init writes only real files inside the project: ${unsafe.join("; ")}. Replace the link with a real file or folder, then run init again.`);
+    }
+    const writesSecret = !!options.webhookUrl || source === "--key" || source === "pasted";
+    if ((io.tracked ?? trackedByGit)(project.dir, project.envFile)) {
+        if (writesSecret) {
+            throw new InitError(`${project.envFile} is tracked by git, so a key written there would be committed with it. Untrack it first: git rm --cached ${project.envFile} (the file stays on disk, and .gitignore then keeps it out). Then run init again.`);
+        }
+        result.notes.push(`${project.envFile} is tracked by git: keep keys out of it until it is untracked (git rm --cached ${project.envFile}).`);
+    }
     // The network first: if Perly Pay refuses the endpoint, nothing has been written yet.
     let webhookSecret = null;
     result.webhook = null;
@@ -167,8 +227,8 @@ async function run(options, io, result) {
     if (ignored !== null && !options.dryRun)
         writeFileSync(gitignorePath, ignored);
     const next = result.next;
-    if (!project.hasSdk) {
-        const command = installCommand(project);
+    const command = project.hasSdk ? null : installCommand(project);
+    if (command) {
         if (options.install && !options.dryRun) {
             const status = io.run(command, project.dir);
             result.install = { command, ran: true, status };

package/dist/cli/main.js

@@ -33,7 +33,7 @@ Options
   --force                 replace files and values that are already there
   --plugin                print how to add the Claude Code plugin
   --mcp                   print the MCP server config (${"perly-pay-mcp"})
-  --api <origin>          Perly Pay's address (default ${DEFAULT_API})
+  --api <origin>          Perly Pay's address (default ${DEFAULT_API}; plain http only for localhost)
   --dir <path>            the project (default: here)
   --dry-run               say what would happen, write nothing
   --json                  print the result as JSON

package/dist/cli/templates.js

@@ -359,7 +359,9 @@ ${s === "cjs" ? "\nmodule.exports = { perlyPayHandler };\n" : ""}`;
         mount: `${importLine}\n// in http.createServer(async (req, res) => { … }):\nif (await perlyPayHandler(req, res)) return;`,
     };
 }
-// ── Laravel (PHP SDK) ─────────────────────────────────────────────
+// ── Laravel (plain HTTP) ──────────────────────────────────────────
+// Laravel's own HTTP client (Guzzle underneath, already in every Laravel app) and the signature check
+// written out: nothing to install, so the files work before perly/perly-pay is on Packagist.
 const php = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 function laravelFiles(offer) {
     const config = `<?php
@@ -368,20 +370,21 @@ function laravelFiles(offer) {
 return [
     'secret_key' => env('${KEY_VAR}'),
     'webhook_secret' => env('${WEBHOOK_SECRET_VAR}'),
-    'api' => env('${API_VAR}'),
+    'api' => env('${API_VAR}', 'https://pay.perly.io'),
 ];
 `;
     const controller = `<?php
 
 namespace App\\Http\\Controllers;
 
+use Illuminate\\Http\\Client\\RequestException;
 use Illuminate\\Http\\Request;
-use Perly\\Pay\\Exception\\SignatureVerificationException;
-use Perly\\Pay\\PerlyPay;
-use Perly\\Pay\\Webhook;
+use Illuminate\\Support\\Facades\\Http;
+use Illuminate\\Support\\Str;
 
 /**
  * Perly Pay: crypto payments straight to your wallet.
+ * Calls the REST API with Laravel's HTTP client: https://pay.perly.io/docs/api
  * ${HEADER}
  */
 class PerlyPayController extends Controller
@@ -392,6 +395,9 @@ class PerlyPayController extends Controller
         'credits_100' => ['description' => '100 credits', 'amount' => 1000, 'currency' => '${offer.currency}', 'credits' => 100],
     ];
 
+    /** How old a webhook's signature may be, in seconds. */
+    private const TOLERANCE = 300;
+
     /** Try it: a page with the button. */
     public function button()
     {
@@ -410,13 +416,21 @@ class PerlyPayController extends Controller
         if ($request->filled('user')) {
             $metadata['user'] = (string) $request->input('user');
         }
-        $invoice = $this->client()->invoices->create([
-            'amount' => $plan['amount'],
-            'currency' => $plan['currency'],
-            'description' => $plan['description'],
-            'return_url' => url('/'),
-            'metadata' => $metadata,
-        ]);
+        $invoice = Http::withToken((string) config('perly-pay.secret_key'))
+            ->acceptJson()
+            // The same key on a retry opens the same invoice, never a second one.
+            ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
+            // A dropped connection, 429 or 5xx is tried again (twice); anything else is the answer.
+            ->retry(2, 500, fn ($e) => ! $e instanceof RequestException || $e->response->status() === 429 || $e->response->serverError(), throw: false)
+            ->post(rtrim((string) config('perly-pay.api'), '/').'/api/v1/invoices', [
+                'amount' => $plan['amount'],
+                'currency' => $plan['currency'],
+                'description' => $plan['description'],
+                'return_url' => url('/'),
+                'metadata' => $metadata,
+            ])
+            ->throw()
+            ->json();
 
         return redirect()->away($invoice['url'], 303);
     }
@@ -428,11 +442,10 @@ class PerlyPayController extends Controller
         if ($secret === '') {
             return response('${WEBHOOK_SECRET_VAR} is not set.', 500);
         }
-        try {
-            // The RAW body, not the parsed request.
-            $event = Webhook::verify($request->getContent(), $request->header('Perly-Signature'), $secret);
-        } catch (SignatureVerificationException $e) {
-            return response($e->getMessage(), 400);
+        // The RAW body, not the parsed request.
+        $event = $this->verify($request->getContent(), $request->header('Perly-Signature'), $secret);
+        if ($event === null) {
+            return response('Bad signature.', 400);
         }
         if (($event['type'] ?? '') === 'invoice.fulfilled') {
             $this->grantAccess($event['data']['object']);
@@ -452,11 +465,33 @@ class PerlyPayController extends Controller
         logger()->info('[perly-pay] '.$invoice['id'].' fulfilled', $meta);
     }
 
-    private function client(): PerlyPay
+    /**
+     * Perly-Signature is "t=<unix seconds>,v1=<hex>", v1 = HMAC-SHA256(secret, t.".".body).
+     * The event when a v1 matches and t is under five minutes old; null otherwise.
+     */
+    private function verify(string $payload, ?string $header, string $secret): ?array
     {
-        $api = config('perly-pay.api');
+        $timestamp = null;
+        $signatures = [];
+        foreach (explode(',', (string) $header) as $part) {
+            [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
+            if ($key === 't' && preg_match('/^\\d{1,12}$/', $value) === 1) {
+                $timestamp = (int) $value;
+            } elseif ($key === 'v1' && preg_match('/^[0-9a-fA-F]{64}$/', $value) === 1) {
+                $signatures[] = strtolower($value);
+            }
+        }
+        if ($timestamp === null || $signatures === [] || abs(time() - $timestamp) > self::TOLERANCE) {
+            return null;
+        }
+        $expected = hash_hmac('sha256', $timestamp.'.'.$payload, $secret);
+        $matched = false;
+        foreach ($signatures as $signature) {
+            $matched = hash_equals($expected, $signature) || $matched;
+        }
+        $event = $matched ? json_decode($payload, true) : null;
 
-        return new PerlyPay((string) config('perly-pay.secret_key'), $api ? ['base_url' => $api] : []);
+        return is_array($event) ? $event : null;
     }
 }
 `;

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.1.1";
 export interface HttpOptions {
     /** Empty for the public endpoints (license checks from your app). */
     secretKey: string;

package/dist/http.js

@@ -5,7 +5,7 @@
  * errors (honouring Retry-After), and a timeout. Plain `fetch`.
  */
 import { ConnectionError, PerlyPayError } from "./errors.js";
-export const SDK_VERSION = "0.1.0";
+export const SDK_VERSION = "0.1.1";
 function uuid() {
     if (typeof globalThis.crypto?.randomUUID === "function")
         return globalThis.crypto.randomUUID();

package/dist/index.d.ts

@@ -244,7 +244,7 @@ export declare class PerlyPay {
     readonly webhookEndpoints: WebhookEndpoints;
     readonly webhooks: typeof webhooks;
     constructor(secretKey: string, options?: PerlyPayOptions);
-    static readonly VERSION = "0.1.0";
+    static readonly VERSION = "0.1.1";
 }
 /**
  * License checks from YOUR app (a desktop app, a plugin, a CLI) — no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perly-pay",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Perly Pay's server SDK: crypto payments straight to your wallet. Zero dependencies, fetch-based, typed.",
   "license": "MIT",
   "author": "Perly (https://pay.perly.io)",