@percher/shared 0.1.2 → 0.1.4

package/dist/app-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Valid app name: 3–40 chars, lowercase, starts with a letter,
+ * [a-z0-9-] only. App names become subdomains (name.percher.run),
+ * so changing this changes what hostnames the platform accepts.
+ */
+export declare const APP_NAME_RE: RegExp;
+//# sourceMappingURL=app-name.d.ts.map

package/dist/app-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-name.d.ts","sourceRoot":"","sources":["../src/app-name.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAA2B,CAAC"}

package/dist/app-name.js

@@ -0,0 +1,7 @@
+/**
+ * Valid app name: 3–40 chars, lowercase, starts with a letter,
+ * [a-z0-9-] only. App names become subdomains (name.percher.run),
+ * so changing this changes what hostnames the platform accepts.
+ */
+export const APP_NAME_RE = /^[a-z][a-z0-9-]{2,39}$/;
+//# sourceMappingURL=app-name.js.map

package/dist/app-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-name.js","sourceRoot":"","sources":["../src/app-name.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,wBAAwB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
+export { APP_NAME_RE } from "./app-name";
+export { MAX_TARBALL_BYTES } from "./limits";
 export { MAX_LOG_SEARCH_LENGTH } from "./logs";
+export { canonicalInjectedKey, isPercherInjected, PERCHER_INJECTED_ENV_KEYS, } from "./platform-env";
 export { DEFAULT_NODE_VERSION_LABEL, DEFAULT_NODE_VERSION_MAJOR } from "./runtime";
 export { TIMEOUTS, type TimeoutKey } from "./timeouts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,7 @@
+export { APP_NAME_RE } from "./app-name";
+export { MAX_TARBALL_BYTES } from "./limits";
 export { MAX_LOG_SEARCH_LENGTH } from "./logs";
+export { canonicalInjectedKey, isPercherInjected, PERCHER_INJECTED_ENV_KEYS, } from "./platform-env";
 export { DEFAULT_NODE_VERSION_LABEL, DEFAULT_NODE_VERSION_MAJOR } from "./runtime";
 export { TIMEOUTS } from "./timeouts";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC"}

package/dist/limits.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Max accepted compressed app-tarball size in bytes (500 MB). Enforced
+ * server-side on upload (Content-Length pre-check + streamed byte cap)
+ * and on GitHub/Forgejo repo imports; the CLI pre-checks before upload.
+ * Distinct from the decompressed extraction cap in the API's tarball
+ * extractor, which guards against zip bombs.
+ */
+export declare const MAX_TARBALL_BYTES: number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAoB,CAAC"}

package/dist/limits.js

@@ -0,0 +1,9 @@
+/**
+ * Max accepted compressed app-tarball size in bytes (500 MB). Enforced
+ * server-side on upload (Content-Length pre-check + streamed byte cap)
+ * and on GitHub/Forgejo repo imports; the CLI pre-checks before upload.
+ * Distinct from the decompressed extraction cap in the API's tarball
+ * extractor, which guards against zip bombs.
+ */
+export const MAX_TARBALL_BYTES = 500 * 1024 * 1024;
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/platform-env.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Env keys Percher injects into every user container at runtime. Treating
+ * these as "missing from your private settings" or "undeclared in
+ * percher.toml" produces false positives — the user can't (and shouldn't)
+ * set them; the platform does. Three consumers must stay locked together:
+ *
+ *   - the source-scan classifier (apps/dashboard env-scan UI hides these)
+ *   - the env gate (packages/api/src/pipeline/env-gate.ts auto-passes them)
+ *   - the AI agent contract (docs/CLAUDE.md "Do NOT include" list)
+ *
+ * Pre-2026-05-29 each consumer kept its own list and they drifted — the
+ * env gate had {NODE_ENV, PORT, DATABASE_URL, POCKETBASE_*, PERCHER_APP_*}
+ * but the dashboard "Scan code" UI had nothing, so it surfaced every
+ * single one as "Referenced in code but missing from your private
+ * settings" and panicked users into setting bogus values.
+ *
+ * Keep this list in lockstep with docs/CLAUDE.md → "Do NOT include
+ * (Percher sets these automatically)" and the egress-proxy wiring
+ * documented under "Outbound HTTPS".
+ */
+export declare const PERCHER_INJECTED_ENV_KEYS: ReadonlySet<string>;
+/**
+ * True iff Percher injects this env key into every user container.
+ *
+ * Case-aware for proxy variants only — POSIX env vars are case-sensitive
+ * in general, but HTTP-proxy libraries by convention accept both cases.
+ * We do NOT case-fold arbitrary keys (PATH vs path are genuinely
+ * different envs to most software).
+ */
+export declare function isPercherInjected(key: string): boolean;
+/**
+ * Canonical (uppercase) form of an injected proxy variant, or the key
+ * unchanged. Used by the scan classifier to collapse `http_proxy` +
+ * `HTTP_PROXY` into a single entry.
+ */
+export declare function canonicalInjectedKey(key: string): string;
+//# sourceMappingURL=platform-env.d.ts.map

package/dist/platform-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-env.d.ts","sourceRoot":"","sources":["../src/platform-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAqBxD,CAAC;AAcH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAItD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/platform-env.js

@@ -0,0 +1,79 @@
+/**
+ * Env keys Percher injects into every user container at runtime. Treating
+ * these as "missing from your private settings" or "undeclared in
+ * percher.toml" produces false positives — the user can't (and shouldn't)
+ * set them; the platform does. Three consumers must stay locked together:
+ *
+ *   - the source-scan classifier (apps/dashboard env-scan UI hides these)
+ *   - the env gate (packages/api/src/pipeline/env-gate.ts auto-passes them)
+ *   - the AI agent contract (docs/CLAUDE.md "Do NOT include" list)
+ *
+ * Pre-2026-05-29 each consumer kept its own list and they drifted — the
+ * env gate had {NODE_ENV, PORT, DATABASE_URL, POCKETBASE_*, PERCHER_APP_*}
+ * but the dashboard "Scan code" UI had nothing, so it surfaced every
+ * single one as "Referenced in code but missing from your private
+ * settings" and panicked users into setting bogus values.
+ *
+ * Keep this list in lockstep with docs/CLAUDE.md → "Do NOT include
+ * (Percher sets these automatically)" and the egress-proxy wiring
+ * documented under "Outbound HTTPS".
+ */
+export const PERCHER_INJECTED_ENV_KEYS = new Set([
+    // Container fundamentals
+    "NODE_ENV",
+    "PORT",
+    // Data backends (mode-specific but always one or the other; both safe
+    // to list — a key that's never set in the container still doesn't
+    // belong in the user's "private settings" UI)
+    "DATABASE_URL",
+    "POCKETBASE_URL",
+    "POCKETBASE_ADMIN_EMAIL",
+    "POCKETBASE_ADMIN_PASSWORD",
+    // App identity
+    "PERCHER_APP_NAME",
+    "PERCHER_APP_URL",
+    // Egress proxy (Percher injects these so app code can reach the
+    // public internet through the forward proxy — see docs/CLAUDE.md
+    // "Outbound HTTPS")
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "NODE_USE_ENV_PROXY",
+]);
+/**
+ * Lowercase proxy variants that libraries (curl, requests, undici-via-
+ * NODE_USE_ENV_PROXY) accept interchangeably with the uppercase form.
+ * Treated as the same env at classification time so the scan UI doesn't
+ * show duplicate "missing" rows for `HTTP_PROXY` and `http_proxy`.
+ */
+const PROXY_LOWERCASE_ALIASES = new Set([
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+]);
+/**
+ * True iff Percher injects this env key into every user container.
+ *
+ * Case-aware for proxy variants only — POSIX env vars are case-sensitive
+ * in general, but HTTP-proxy libraries by convention accept both cases.
+ * We do NOT case-fold arbitrary keys (PATH vs path are genuinely
+ * different envs to most software).
+ */
+export function isPercherInjected(key) {
+    if (PERCHER_INJECTED_ENV_KEYS.has(key))
+        return true;
+    if (PROXY_LOWERCASE_ALIASES.has(key))
+        return true;
+    return false;
+}
+/**
+ * Canonical (uppercase) form of an injected proxy variant, or the key
+ * unchanged. Used by the scan classifier to collapse `http_proxy` +
+ * `HTTP_PROXY` into a single entry.
+ */
+export function canonicalInjectedKey(key) {
+    if (PROXY_LOWERCASE_ALIASES.has(key))
+        return key.toUpperCase();
+    return key;
+}
+//# sourceMappingURL=platform-env.js.map

package/dist/platform-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-env.js","sourceRoot":"","sources":["../src/platform-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAS;IAC5E,yBAAyB;IACzB,UAAU;IACV,MAAM;IACN,sEAAsE;IACtE,kEAAkE;IAClE,8CAA8C;IAC9C,cAAc;IACd,gBAAgB;IAChB,wBAAwB;IACxB,2BAA2B;IAC3B,eAAe;IACf,kBAAkB;IAClB,iBAAiB;IACjB,gEAAgE;IAChE,iEAAiE;IACjE,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,UAAU;IACV,oBAAoB;CACrB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAS;IACnE,YAAY;IACZ,aAAa;IACb,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,yBAAyB,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,uBAAuB,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,uBAAuB,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;IAC/D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/pow.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Proof-of-work for the headless anonymous-deploy gate (FUTURE23 Spår A
+ * hardening). A solution is any string such that
+ * `sha256(`${nonce}:${solution}`)` has at least `difficulty` leading zero
+ * bits. Lives in @percher/shared so the API verifies with the EXACT algorithm
+ * the CLI/MCP client solves — a drift between the two would silently reject
+ * every legitimate publish or accept unsolved ones.
+ *
+ * A browser CAPTCHA can't gate this endpoint: the caller is a headless agent
+ * or CLI. PoW is the headless equivalent — the client spends CPU instead of a
+ * human solving a puzzle, so a botnet pays a real cost per app regardless of
+ * how many IPs it controls.
+ */
+export declare const POW_ALGORITHM = "sha256-leading-zero-bits";
+/** Count leading zero bits in a hex digest. */
+export declare function leadingZeroBits(hexDigest: string): number;
+/** True if `solution` meets `difficulty` for `nonce`. difficulty<=0 is a no-op. */
+export declare function verifyPow(nonce: string, solution: string, difficulty: number): boolean;
+/**
+ * Brute-force a solution. Returns the first hit, or null if `maxIterations` is
+ * exhausted (guards against a pathological difficulty hanging the client).
+ */
+export declare function solvePow(nonce: string, difficulty: number, maxIterations?: number): string | null;
+//# sourceMappingURL=pow.d.ts.map

package/dist/pow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pow.d.ts","sourceRoot":"","sources":["../src/pow.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAMxD,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAazD;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAItF;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,aAAa,SAAa,GACzB,MAAM,GAAG,IAAI,CAOf"}

package/dist/pow.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+/**
+ * Proof-of-work for the headless anonymous-deploy gate (FUTURE23 Spår A
+ * hardening). A solution is any string such that
+ * `sha256(`${nonce}:${solution}`)` has at least `difficulty` leading zero
+ * bits. Lives in @percher/shared so the API verifies with the EXACT algorithm
+ * the CLI/MCP client solves — a drift between the two would silently reject
+ * every legitimate publish or accept unsolved ones.
+ *
+ * A browser CAPTCHA can't gate this endpoint: the caller is a headless agent
+ * or CLI. PoW is the headless equivalent — the client spends CPU instead of a
+ * human solving a puzzle, so a botnet pays a real cost per app regardless of
+ * how many IPs it controls.
+ */
+export const POW_ALGORITHM = "sha256-leading-zero-bits";
+function digest(nonce, solution) {
+    return createHash("sha256").update(`${nonce}:${solution}`).digest("hex");
+}
+/** Count leading zero bits in a hex digest. */
+export function leadingZeroBits(hexDigest) {
+    let bits = 0;
+    for (const ch of hexDigest) {
+        const nibble = Number.parseInt(ch, 16);
+        if (nibble === 0) {
+            bits += 4;
+            continue;
+        }
+        // clz32(n) - 28 = leading zeros of a 4-bit value (1..15).
+        bits += Math.clz32(nibble) - 28;
+        break;
+    }
+    return bits;
+}
+/** True if `solution` meets `difficulty` for `nonce`. difficulty<=0 is a no-op. */
+export function verifyPow(nonce, solution, difficulty) {
+    if (difficulty <= 0)
+        return true;
+    if (!solution)
+        return false;
+    return leadingZeroBits(digest(nonce, solution)) >= difficulty;
+}
+/**
+ * Brute-force a solution. Returns the first hit, or null if `maxIterations` is
+ * exhausted (guards against a pathological difficulty hanging the client).
+ */
+export function solvePow(nonce, difficulty, maxIterations = 50_000_000) {
+    if (difficulty <= 0)
+        return "0";
+    for (let i = 0; i < maxIterations; i++) {
+        const solution = i.toString(36);
+        if (leadingZeroBits(digest(nonce, solution)) >= difficulty)
+            return solution;
+    }
+    return null;
+}
+//# sourceMappingURL=pow.js.map

package/dist/pow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pow.js","sourceRoot":"","sources":["../src/pow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,0BAA0B,CAAC;AAExD,SAAS,MAAM,CAAC,KAAa,EAAE,QAAgB;IAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,CAAC;YACV,SAAS;QACX,CAAC;QACD,0DAA0D;QAC1D,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM;IACR,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,QAAgB,EAAE,UAAkB;IAC3E,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,UAAU,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAa,EACb,UAAkB,EAClB,aAAa,GAAG,UAAU;IAE1B,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,UAAU;YAAE,OAAO,QAAQ,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percher/shared",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Shared constants and contracts (timeouts, etc.) used across the Percher CLI, API, MCP, and worker. Internal — values change in lockstep across packages.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,6 +20,16 @@
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
       "default": "./dist/runtime.js"
+    },
+    "./platform-env": {
+      "types": "./dist/platform-env.d.ts",
+      "import": "./dist/platform-env.js",
+      "default": "./dist/platform-env.js"
+    },
+    "./pow": {
+      "types": "./dist/pow.d.ts",
+      "import": "./dist/pow.js",
+      "default": "./dist/pow.js"
     }
   },
   "files": [