@x1id/resolve 0.15.0 → 0.15.1

package/README.md

@@ -366,10 +366,22 @@ export async function POST(req: Request) {           // any server runtime with
 }
 ```
 
-Fail-closed by default (re-throws if the decision can't be obtained; pass
-`{ onError: "allow" }` to fail-open). `checkGate()` is the lower-level client for
-the full decision; pass a stored policy's `gp_…` id as the policy to reuse a named
-policy. The hosted check is keyed/metered — see `services/dev-api`'s README.
+Fail-closed by default (re-throws if the decision can't be obtained). `onError:
+"deny"` fails closed without throwing (clean `allowed: false`). `checkGate()` is
+the lower-level client for the full decision; pass a stored policy's `gp_…` id as
+the policy to reuse a named policy. The hosted check is keyed/metered — see
+`services/dev-api`'s README.
+
+> **⚠️ Never use `onError: "allow"` on a real gate.** It FAILS OPEN: on *any*
+> error — a network blip, a timeout, a 5xx, an auth failure, a malformed
+> response — it fabricates a `passed: true` decision and admits the caller
+> **unverified**. Anyone who can make your gate call fail (trivially: induce a
+> timeout) then bypasses the gate completely, so it is worse than no gate at all
+> for anything it protects — a route, a mint, an airdrop, a write, an allowlist.
+> It exists ONLY for soft, non-security personalization where a missing
+> verification must not degrade UX (e.g. optionally showing a "verified"
+> flourish). Using it logs a one-time `console.warn`. If the decision gates
+> anything, use the default `"throw"` or `"deny"`.
 
 ## What works today
 

package/dist/gateClient.d.ts

@@ -80,14 +80,16 @@ export interface GuardResult {
  * silently admitting an unverified caller. `onError: "deny"` instead resolves to
  * a clean `allowed: false` (fail-closed without a throw).
  *
- * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
- * timeout, 5xx, auth failure, a malformed response) it fabricates a
- * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
- * real access gate — anyone who can make your gate call fail (trivial: induce a
- * timeout) then bypasses it completely. It exists ONLY for soft, non-security
- * personalization where a missing verification must not degrade UX (e.g.
- * optionally showing a "verified" flourish). If the gate protects anything —
- * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN, and is NEVER acceptable on a real
+ * gate. On ANY error (network blip, timeout, 5xx, auth failure, a malformed
+ * response) it fabricates a `passed: true` decision and admits the caller
+ * UNVERIFIED — so anyone who can make your gate call fail (trivial: induce a
+ * timeout) bypasses it completely. That makes it strictly WORSE than no gate for
+ * anything it is supposed to protect: a route, a mint, an airdrop, a write, an
+ * allowlist. It exists ONLY for soft, non-security personalization where a
+ * missing verification must not degrade UX (e.g. optionally showing a "verified"
+ * flourish). Constructing a guard with it logs a one-time `console.warn`. If the
+ * decision gates ANYTHING, use the default `"throw"` or `"deny"` (fail-closed).
  *
  * @example
  * ```ts

package/dist/gateClient.js

@@ -81,14 +81,16 @@ export async function checkGate(cfg, subject, policy) {
  * silently admitting an unverified caller. `onError: "deny"` instead resolves to
  * a clean `allowed: false` (fail-closed without a throw).
  *
- * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
- * timeout, 5xx, auth failure, a malformed response) it fabricates a
- * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
- * real access gate — anyone who can make your gate call fail (trivial: induce a
- * timeout) then bypasses it completely. It exists ONLY for soft, non-security
- * personalization where a missing verification must not degrade UX (e.g.
- * optionally showing a "verified" flourish). If the gate protects anything —
- * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN, and is NEVER acceptable on a real
+ * gate. On ANY error (network blip, timeout, 5xx, auth failure, a malformed
+ * response) it fabricates a `passed: true` decision and admits the caller
+ * UNVERIFIED — so anyone who can make your gate call fail (trivial: induce a
+ * timeout) bypasses it completely. That makes it strictly WORSE than no gate for
+ * anything it is supposed to protect: a route, a mint, an airdrop, a write, an
+ * allowlist. It exists ONLY for soft, non-security personalization where a
+ * missing verification must not degrade UX (e.g. optionally showing a "verified"
+ * flourish). Constructing a guard with it logs a one-time `console.warn`. If the
+ * decision gates ANYTHING, use the default `"throw"` or `"deny"` (fail-closed).
  *
  * @example
  * ```ts
@@ -106,6 +108,10 @@ export async function checkGate(cfg, subject, policy) {
  */
 export function requireGate(cfg, policy, opts = {}) {
     const onError = opts.onError ?? "throw";
+    // Warn HARD (once) the moment a fail-open guard is built — `onError: "allow"`
+    // admits unverified callers on any error and must never guard anything real.
+    if (onError === "allow")
+        warnFailOpenOnce();
     return async (subject) => {
         try {
             const decision = await checkGate(cfg, subject, policy);
@@ -126,3 +132,16 @@ export function requireGate(cfg, policy, opts = {}) {
         }
     };
 }
+/** Process-wide latch so the fail-open warning fires at most once, not on every
+ *  guard construction. */
+let failOpenWarned = false;
+function warnFailOpenOnce() {
+    if (failOpenWarned)
+        return;
+    failOpenWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn("[@x1id/resolve] requireGate({ onError: \"allow\" }) FAILS OPEN: on any gate-call " +
+        "error it admits the caller UNVERIFIED. Never use it to protect a route, mint, " +
+        "airdrop, write, or allowlist — use the default \"throw\" or \"deny\" instead. " +
+        "(This warning is for soft personalization-only uses; it logs once.)");
+}

package/dist/signin.js

@@ -78,6 +78,14 @@ export class SignInError extends Error {
  *  belt-and-suspenders CR/LF guard in {@link createSignInChallenge} mirrors the
  *  `uri`/`statement` fields and is the real anti-injection control. */
 const DOMAIN_RE = /^[A-Za-z0-9.-]{1,253}(:\d{1,5})?$/;
+/** Any character a line-oriented parser could mistake for a boundary: every C0
+ *  control (so `\n`, `\r`, `\t`, and the rest), DEL, and — the trap the old
+ *  `\n`/`\r`-only guard missed — the Unicode line/paragraph separators
+ *  U+2028/U+2029, which `^`/`$` under the regex `m` flag honor just like `\n`
+ *  (see {@link parseSignInChallenge}'s field parser). FORBIDDEN in every value
+ *  interpolated into a challenge line (domain, statement, uri) so a crafted
+ *  value can never forge a second line — challenge-line injection (audit L5). */
+const FORBIDDEN_LINE_CHAR_RE = /[\u0000-\u001f\u007f\u2028\u2029]/;
 /** Nonce charset — ASCII alphanumeric, matching the rest of the SDK's nonces so
  *  it can never contain a separator or a newline. SIWE requires >= 8 chars. */
 const NONCE_RE = /^[0-9A-Za-z]{8,128}$/;
@@ -124,11 +132,14 @@ export function generateSignInNonce(bytes = 16) {
  */
 export function createSignInChallenge(params) {
     const { domain } = params;
-    // Explicit CR/LF guard first — mirrors the `uri`/`statement` fields below and
-    // makes the anti-challenge-injection intent impossible to regress even if the
-    // charset in DOMAIN_RE is ever loosened.
-    if (typeof domain !== "string" || domain.includes("\n") || domain.includes("\r") || !DOMAIN_RE.test(domain)) {
-        throw new SignInError("invalid-params", "domain must be a single DNS host (letters, digits, '.', '-'), no newlines");
+    // Explicit control/line-terminator guard first — mirrors the `uri`/`statement`
+    // fields below and makes the anti-challenge-injection intent impossible to
+    // regress even if the charset in DOMAIN_RE is ever loosened. DOMAIN_RE already
+    // admits only `[A-Za-z0-9.-]` (+ optional `:port`), so this is belt-and-
+    // suspenders — but it is the control that catches EVERY forbidden boundary
+    // char (incl. `\t`, U+2028/U+2029), not just `\n`/`\r` (audit L5).
+    if (typeof domain !== "string" || FORBIDDEN_LINE_CHAR_RE.test(domain) || !DOMAIN_RE.test(domain)) {
+        throw new SignInError("invalid-params", "domain must be a single DNS host (letters, digits, '.', '-'), no control characters");
     }
     if (!decodeBase58_32(params.address)) {
         throw new SignInError("invalid-params", `"${params.address}" is not a valid X1 address`);
@@ -137,12 +148,12 @@ export function createSignInChallenge(params) {
     // the signer and the verifier both compare against.
     const address = encodeBase58(decodeBase58_32(params.address));
     const statement = params.statement ?? null;
-    if (statement !== null && (statement.includes("\n") || statement.includes("\r") || statement.length === 0)) {
-        throw new SignInError("invalid-params", "statement must be a single non-empty line");
+    if (statement !== null && (FORBIDDEN_LINE_CHAR_RE.test(statement) || statement.length === 0)) {
+        throw new SignInError("invalid-params", "statement must be a single non-empty line (no control characters)");
     }
     const uri = params.uri ?? `https://${domain}`;
-    if (uri.includes("\n") || uri.includes("\r")) {
-        throw new SignInError("invalid-params", "uri must be a single line");
+    if (FORBIDDEN_LINE_CHAR_RE.test(uri)) {
+        throw new SignInError("invalid-params", "uri must be a single line (no control characters)");
     }
     const nonce = params.nonce ?? generateSignInNonce();
     if (!NONCE_RE.test(nonce)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",