@greatwait/contracts 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/oauth.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import { SCOPES, environmentKindSchema, scopeSchema, } from "./authority.js";
 import { oauthClientIdSchema, oauthGrantIdSchema, projectIdSchema, } from "./identifiers.js";
 import { timestampSchema } from "./time.js";
@@ -273,9 +273,32 @@ export const OAUTH_SECRET_PATTERN = /^o(?:at|rt|ac)_(?:live|test)_[0-9a-z]{48}$/
  * - `http://` on a loopback host only — `127.0.0.1`, `[::1]`, `localhost`. A
  *   native client receives its code on a listener it started itself, and there
  *   is no TLS to have. Refusing these would refuse every desktop MCP client.
- * - a private-use scheme containing a dot, such as `com.example.app:/callback`.
- *   RFC 8252 §7.1's reverse-domain form, which is what a mobile or editor client
- *   registers.
+ * - a private-use scheme whose URI is hierarchical, such as
+ *   `com.example.app:/callback` or `cursor://anysphere.cursor-mcp/oauth/callback`.
+ *   This is what a desktop or editor client registers.
+ *
+ * **The reverse-domain requirement was removed at W9-02, and the reason is that
+ * it refused a real client and bought nothing.** It required a dot in the
+ * scheme, on RFC 8252 §7.1's advice that an app choose a scheme "based on a
+ * domain name under their control, expressed in reverse order". That is
+ * guidance to *app authors*; nothing asks an authorization server to police it,
+ * and it stops no attacker — a scheme is claimed first-come by whatever
+ * installs, and an attacker can claim `com.cursor.app` as easily as `cursor`.
+ * What actually defends a public client against code interception is mandatory
+ * S256 PKCE, exact redirect matching, and a single-use code that ends its grant
+ * on replay, and this server requires all three. Meanwhile the rule refused
+ * `cursor://anysphere.cursor-mcp/oauth/callback` outright, so Cursor could not
+ * complete dynamic registration at all — observed against a hosted stage, while
+ * Linear's registration endpoint accepts that exact value.
+ *
+ * **What replaces it is structural, and it has to be.** Simply deleting the dot
+ * check would accept `javascript:alert(1)` as a redirect URI, and the consent
+ * screen navigates to the value this schema approved — which is script
+ * execution in the dashboard's own origin. So a private-use scheme is accepted
+ * only when its URI is *hierarchical*: `pathname` begins with `/`, which is the
+ * shape RFC 8252 §7.1's own examples have and which `javascript:`, `data:` and
+ * `mailto:` do not. A short deny list sits in front of that for the schemes
+ * that are hierarchical and still must never be a redirect target.
  *
  * A fragment is refused outright: RFC 6749 §3.1.2 forbids one, and the fragment
  * is where the server appends nothing and the browser strips everything, so a
@@ -287,6 +310,48 @@ export const OAUTH_SECRET_PATTERN = /^o(?:at|rt|ac)_(?:live|test)_[0-9a-z]{48}$/
  * exact judgement.
  */
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "::1", "localhost"]);
+/**
+ * Schemes that are never a redirect target, whatever their shape.
+ *
+ * The hierarchical test below excludes the opaque ones on its own; these are
+ * the schemes that pass it and must still be refused. `file:` is the reason the
+ * list is not empty — `file:///etc/passwd` is perfectly hierarchical — and the
+ * rest are here because a deny list somebody has to remember to extend is worth
+ * less than one that already covers the obvious neighbours.
+ */
+const DENIED_SCHEMES = new Set([
+    // Opaque or script-bearing. The hierarchical test below catches most
+    // spellings of these on its own; `javascript://x/%0aalert(1)` is the one it
+    // cannot, which is why this list is not empty.
+    "about",
+    "blob",
+    "data",
+    "filesystem",
+    "javascript",
+    "vbscript",
+    // Hierarchical, and never a redirect target. `file:///etc/passwd` parses
+    // perfectly.
+    "file",
+    // **Registered schemes, which are by definition not private-use.** A review
+    // pointed out that the hierarchical test alone accepts `ws://`,
+    // `chrome-extension://` and friends: any scheme with an authority and a
+    // leading-slash path. No exploit follows — a redirect must still exactly
+    // match one the client registered for itself, so an attacker controls their
+    // own target through plain `https` anyway — but a redirect URI naming a
+    // scheme somebody else owns is not what "private-use" means, and refusing the
+    // well-known ones costs nothing.
+    "chrome",
+    "chrome-extension",
+    "edge",
+    "ftp",
+    "ftps",
+    "intent",
+    "moz-extension",
+    "resource",
+    "view-source",
+    "ws",
+    "wss",
+]);
 export const redirectUriSchema = z
     .string()
     .min(1)
@@ -327,12 +392,23 @@ export const redirectUriSchema = z
         }
         return;
     }
-    // A private-use scheme. The dot is RFC 8252's own test for one, and it is
-    // what keeps `myapp:/callback` — a scheme anybody could claim — out.
-    if (!url.protocol.slice(0, -1).includes(".")) {
+    // A private-use scheme.
+    const scheme = url.protocol.slice(0, -1);
+    if (DENIED_SCHEMES.has(scheme)) {
+        context.addIssue({
+            code: "custom",
+            message: `${scheme} is never a redirect target`,
+        });
+        return;
+    }
+    // Hierarchical, which is what tells `com.example.app:/callback` and
+    // `cursor://anysphere.cursor-mcp/oauth/callback` from `javascript:alert(1)`.
+    // The consent screen navigates to whatever this approves, so an opaque URI
+    // reaching here is script execution in the dashboard's own origin.
+    if (!url.pathname.startsWith("/")) {
         context.addIssue({
             code: "custom",
-            message: "must be https, http on a loopback host, or a private-use scheme in reverse-domain form",
+            message: "must be https, http on a loopback host, or a hierarchical private-use scheme such as com.example.app:/callback",
         });
     }
 });

package/dist/operation-definitions.d.ts

@@ -0,0 +1,9 @@
+import type { OperationDefinition } from "./operations.js";
+/** Fail-closed response placeholder used by the hosted API's request-only registry. */
+export declare const API_UNUSED_RESPONSE_SCHEMA: import("zod").ZodNever;
+/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+export declare function defineOperations<const T extends readonly OperationDefinition[]>(definitions: T): {
+    readonly [K in keyof T]: OperationDefinition & {
+        readonly id: T[K]["id"];
+    };
+};

package/dist/operation-definitions.js

@@ -0,0 +1,7 @@
+import { never as neverSchema } from "zod";
+/** Fail-closed response placeholder used by the hosted API's request-only registry. */
+export const API_UNUSED_RESPONSE_SCHEMA = neverSchema();
+/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+export function defineOperations(definitions) {
+    return definitions;
+}