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

package/dist/mcp.d.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+/**
+ * Where the remote MCP surface lives, and what it tells an agent about itself.
+ *
+ * Stated once for the same reason `OAUTH_ROUTES` is: two readers must agree.
+ * The router serves these paths and the protected-resource metadata document
+ * advertises them, and a path that drifts from its advertisement is not a 404 —
+ * it is a client that cannot authenticate and cannot say why.
+ *
+ * Outside `/v1`, following the convention `CLERK_WEBHOOK_PATH` and
+ * `OAUTH_ROUTES` set. The `/v1` surface is the operation registry, every entry
+ * of which is projected into OpenAPI, the SDK, an MCP tool and the contract
+ * mock; the MCP endpoint is the transport those tools are served over, and a
+ * transport that appeared in its own tool list would be a tool an agent could
+ * point at itself.
+ */
+export declare const MCP_ROUTES: {
+    /**
+     * The single Streamable HTTP endpoint. POST only; `GET` and `DELETE` answer
+     * `405`, because this endpoint opens no standalone event stream and mints no
+     * session to terminate.
+     *
+     * Served at this path **and** at the same path with a trailing slash, without
+     * a redirect between them. A `301`/`302` on a POST is rewritten by the fetch
+     * standard into a GET with the body dropped, so a client configured with the
+     * other spelling would have its opening request silently become the GET this
+     * endpoint refuses — and read that as "no MCP server here".
+     */
+    readonly endpoint: "/mcp";
+    /**
+     * RFC 9728 metadata for the MCP endpoint specifically.
+     *
+     * Served *beside* the origin's own document rather than instead of it. RFC
+     * 9728 §3.1 places the metadata for a resource with a path component at
+     * `/.well-known/oauth-protected-resource` followed by that path, so a client
+     * that treats `https://host/mcp` as the resource it is authorizing for
+     * constructs exactly this URL — and one that follows the `resource_metadata`
+     * link out of the `401` is sent here too. Both arrive at a document naming
+     * the same authorization server.
+     */
+    readonly protectedResourceMetadata: "/.well-known/oauth-protected-resource/mcp";
+};
+/**
+ * What the server tells a model about itself, once, before any tool call.
+ *
+ * MCP calls this `instructions` and hands it to the model as context. It is
+ * kept short and factual: an agent that has read the tool descriptions knows
+ * what each one does, and what it cannot work out from them is the shape of the
+ * authority it is acting under — which is the one thing that decides whether an
+ * instruction like "create this in production" is even expressible.
+ */
+export declare const MCP_INSTRUCTIONS: string;
+/**
+ * What a signed-in member is told about a key they have just issued, so that a
+ * connection test can tell "the server refused you" from "the server does not
+ * know this key" from "this key sees fewer tools than you meant it to".
+ *
+ * **Why the endpoint returns the tool names rather than a count.** The
+ * connection test drives `tools/list` through the official MCP client with the
+ * transient secret, and then has to decide whether what came back is about the
+ * credential the member means. A count cannot answer that: two credentials with
+ * different scopes routinely authorize the same number of tools. The names can,
+ * and they are already public — they are the operation ids with underscores,
+ * published in the parity table and in every client's own listing.
+ *
+ * That comparison is what binds the secret in the browser to the credential the
+ * session named. The session's half is the tenant check on the way in: the
+ * route refuses a credential whose authority is not this session's project and
+ * environment, so a member cannot ask this question about another tenant's key.
+ */
+export declare const MCP_CONNECTION_STATES: readonly ["usable", "revoked", "expired"];
+export type McpConnectionState = (typeof MCP_CONNECTION_STATES)[number];
+/**
+ * The steps a connection test performs, in order, and the only steps it has.
+ *
+ * Closed because the result is reported as an activation fact, and an open list
+ * of step names is a free-text field with a schema in front of it.
+ */
+export declare const MCP_CONNECTION_CHECKS: readonly ["initialize", "tools", "authority"];
+export type McpConnectionCheck = (typeof MCP_CONNECTION_CHECKS)[number];
+/** What a step did. Binary, plus the case where an earlier step stopped it. */
+export declare const MCP_CONNECTION_OUTCOMES: readonly ["passed", "failed", "skipped"];
+export type McpConnectionOutcome = (typeof MCP_CONNECTION_OUTCOMES)[number];
+/**
+ * The bounded answer a connection test starts from.
+ *
+ * Every field is either an address this deployment publishes or a fact about a
+ * credential the caller's own session may already read from the credential
+ * listing. Nothing here is new disclosure, and nothing here is the secret: the
+ * transient value never travels to this route, and the route has nothing it
+ * could echo.
+ */
+export declare const mcpConnectionSchema: z.ZodObject<{
+    discovery: z.ZodString;
+    displayPrefix: z.ZodString;
+    endpoint: z.ZodString;
+    id: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+    state: z.ZodEnum<{
+        revoked: "revoked";
+        usable: "usable";
+        expired: "expired";
+    }>;
+    tools: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type McpConnection = z.infer<typeof mcpConnectionSchema>;
+/**
+ * Why a connection test stopped, from a closed list.
+ *
+ * **Closed because the alternative leaks.** The natural implementation of a
+ * diagnostic is to show what the server said, and what the server said is a
+ * string this product did not write — a proxy's error page, a transport
+ * library's message, a response body. Any of those can carry a URL, a header, or
+ * a fragment of the credential that produced them. A reason from this list
+ * carries none of that and is enough to act on, which is the whole bargain.
+ */
+export declare const MCP_CONNECTION_FAILURES: readonly ["unauthorized", "unreachable", "protocol", "mismatch"];
+export type McpConnectionFailure = (typeof MCP_CONNECTION_FAILURES)[number];
+/**
+ * How long something took, coarsely.
+ *
+ * A duration recorded to the millisecond is a fingerprint: repeated across a
+ * small population it distinguishes one member's connection from another's. The
+ * question an activation fact answers is "was this fast enough to feel like it
+ * worked", and a bucket answers it.
+ */
+export declare const MCP_ACTIVATION_DURATIONS: readonly ["under_1s", "under_5s", "under_30s", "over_30s"];
+export type McpActivationDuration = (typeof MCP_ACTIVATION_DURATIONS)[number];
+/** The bucket a measured duration falls in. */
+export declare function activationDuration(elapsedMs: number): McpActivationDuration;
+/**
+ * What is recorded when somebody connects a client, and the only thing that is.
+ *
+ * **Every field is drawn from a closed set, and that is the point rather than a
+ * convenience.** There is no free-text field, no identifier, no address and no
+ * measurement finer than a bucket, so an event of this shape cannot carry an
+ * account, an organization, a project, an OAuth URL, a token, a destination or a
+ * payload however carelessly it is constructed. The project specification asks
+ * for activation evidence containing "durations and coarse outcomes, never
+ * callback bodies, secrets, tenant identifiers, or customer payloads"; a schema
+ * that admits only those is how that becomes a property instead of a promise.
+ *
+ * `client` is validated against the catalog rather than typed as a string, so a
+ * client nobody has walked cannot appear in activation data as though it had.
+ *
+ * **Strict, not merely typed, and a test is why.** An ordinary object schema
+ * *strips* a field it does not know, which would have made an emitter that added
+ * `project` look like it was recording one while the field silently vanished.
+ * Stripping is safe and dishonest: the caller believes something is being
+ * recorded that is not, and nothing ever tells them. "Closed" has to mean the
+ * schema refuses what it does not recognise, so the mistake surfaces where it
+ * was made.
+ */
+export declare const mcpActivationEventSchema: z.ZodObject<{
+    authKind: z.ZodEnum<{
+        oauth: "oauth";
+        "api-key": "api-key";
+    }>;
+    checks: z.ZodRecord<z.ZodEnum<{
+        authority: "authority";
+        initialize: "initialize";
+        tools: "tools";
+    }>, z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+    }>>;
+    client: z.ZodString;
+    duration: z.ZodEnum<{
+        under_1s: "under_1s";
+        under_5s: "under_5s";
+        under_30s: "under_30s";
+        over_30s: "over_30s";
+    }>;
+    failure: z.ZodOptional<z.ZodEnum<{
+        unauthorized: "unauthorized";
+        unreachable: "unreachable";
+        protocol: "protocol";
+        mismatch: "mismatch";
+    }>>;
+    type: z.ZodLiteral<"mcp.connection_test">;
+}, z.core.$strict>;
+export type McpActivationEvent = z.infer<typeof mcpActivationEventSchema>;

package/dist/mcp.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { scopeSchema } from "./authority.js";
+import { apiCredentialIdSchema } from "./identifiers.js";
+import { CREDENTIAL_PREFIX_PATTERN } from "./secrets.js";
+/**
+ * Where the remote MCP surface lives, and what it tells an agent about itself.
+ *
+ * Stated once for the same reason `OAUTH_ROUTES` is: two readers must agree.
+ * The router serves these paths and the protected-resource metadata document
+ * advertises them, and a path that drifts from its advertisement is not a 404 —
+ * it is a client that cannot authenticate and cannot say why.
+ *
+ * Outside `/v1`, following the convention `CLERK_WEBHOOK_PATH` and
+ * `OAUTH_ROUTES` set. The `/v1` surface is the operation registry, every entry
+ * of which is projected into OpenAPI, the SDK, an MCP tool and the contract
+ * mock; the MCP endpoint is the transport those tools are served over, and a
+ * transport that appeared in its own tool list would be a tool an agent could
+ * point at itself.
+ */
+export const MCP_ROUTES = {
+    /**
+     * The single Streamable HTTP endpoint. POST only; `GET` and `DELETE` answer
+     * `405`, because this endpoint opens no standalone event stream and mints no
+     * session to terminate.
+     *
+     * Served at this path **and** at the same path with a trailing slash, without
+     * a redirect between them. A `301`/`302` on a POST is rewritten by the fetch
+     * standard into a GET with the body dropped, so a client configured with the
+     * other spelling would have its opening request silently become the GET this
+     * endpoint refuses — and read that as "no MCP server here".
+     */
+    endpoint: "/mcp",
+    /**
+     * RFC 9728 metadata for the MCP endpoint specifically.
+     *
+     * Served *beside* the origin's own document rather than instead of it. RFC
+     * 9728 §3.1 places the metadata for a resource with a path component at
+     * `/.well-known/oauth-protected-resource` followed by that path, so a client
+     * that treats `https://host/mcp` as the resource it is authorizing for
+     * constructs exactly this URL — and one that follows the `resource_metadata`
+     * link out of the `401` is sent here too. Both arrive at a document naming
+     * the same authorization server.
+     */
+    protectedResourceMetadata: "/.well-known/oauth-protected-resource/mcp",
+};
+/**
+ * What the server tells a model about itself, once, before any tool call.
+ *
+ * MCP calls this `instructions` and hands it to the model as context. It is
+ * kept short and factual: an agent that has read the tool descriptions knows
+ * what each one does, and what it cannot work out from them is the shape of the
+ * authority it is acting under — which is the one thing that decides whether an
+ * instruction like "create this in production" is even expressible.
+ */
+export const MCP_INSTRUCTIONS = [
+    "Greatwait schedules work and delivers it to an endpoint at the time asked for.",
+    "Every tool acts inside one organization, project and environment, fixed by the credential this connection was authorized with; no argument can name another, and there is no tool that moves between them.",
+    "Reads are safe to repeat. Writes are annotated, and the ones marked destructive settle or discard an occurrence that would otherwise have fired.",
+    "A refusal comes back as a problem document with a stable `code`: act on the code, not on the wording.",
+].join(" ");
+/**
+ * What a signed-in member is told about a key they have just issued, so that a
+ * connection test can tell "the server refused you" from "the server does not
+ * know this key" from "this key sees fewer tools than you meant it to".
+ *
+ * **Why the endpoint returns the tool names rather than a count.** The
+ * connection test drives `tools/list` through the official MCP client with the
+ * transient secret, and then has to decide whether what came back is about the
+ * credential the member means. A count cannot answer that: two credentials with
+ * different scopes routinely authorize the same number of tools. The names can,
+ * and they are already public — they are the operation ids with underscores,
+ * published in the parity table and in every client's own listing.
+ *
+ * That comparison is what binds the secret in the browser to the credential the
+ * session named. The session's half is the tenant check on the way in: the
+ * route refuses a credential whose authority is not this session's project and
+ * environment, so a member cannot ask this question about another tenant's key.
+ */
+export const MCP_CONNECTION_STATES = ["usable", "revoked", "expired"];
+/**
+ * The steps a connection test performs, in order, and the only steps it has.
+ *
+ * Closed because the result is reported as an activation fact, and an open list
+ * of step names is a free-text field with a schema in front of it.
+ */
+export const MCP_CONNECTION_CHECKS = [
+    /** The client completed the MCP handshake against the endpoint. */
+    "initialize",
+    /** The client listed tools, and the listing was well formed. */
+    "tools",
+    /** The listing was the one this credential's scopes authorize. */
+    "authority",
+];
+/** What a step did. Binary, plus the case where an earlier step stopped it. */
+export const MCP_CONNECTION_OUTCOMES = ["passed", "failed", "skipped"];
+/**
+ * The bounded answer a connection test starts from.
+ *
+ * Every field is either an address this deployment publishes or a fact about a
+ * credential the caller's own session may already read from the credential
+ * listing. Nothing here is new disclosure, and nothing here is the secret: the
+ * transient value never travels to this route, and the route has nothing it
+ * could echo.
+ */
+export const mcpConnectionSchema = z.object({
+    /** The RFC 9728 document for the endpoint, absolute. */
+    discovery: z.string().url(),
+    /** The non-secret leading segment, so a client can check it holds this key. */
+    displayPrefix: z.string().regex(CREDENTIAL_PREFIX_PATTERN),
+    /** The Streamable HTTP endpoint, absolute, ready to paste. */
+    endpoint: z.string().url(),
+    /**
+     * Which credential this describes.
+     *
+     * A document addressed by an identifier echoes it — the rule
+     * `published-examples.worker.test.ts` enforces on every read, and the reason
+     * is a caller holding two of these needing to tell them apart. The display
+     * prefix is a recognition aid rather than an identity, and it is not the value
+     * a later call is addressed by.
+     */
+    id: apiCredentialIdSchema,
+    /** The scopes fixed into this credential when it was issued. */
+    scopes: z.array(scopeSchema),
+    state: z.enum(MCP_CONNECTION_STATES),
+    /**
+     * The MCP tool names these scopes authorize, sorted.
+     *
+     * Computed by the same authorization policy `/mcp` runs when it decides what
+     * to put in `tools/list`, rather than by a second rule that would drift from
+     * it. A connection test compares this against what the official client
+     * actually listed; equal means the secret in the browser is the credential the
+     * session named, and unequal means it is not — which no count could tell them.
+     */
+    tools: z.array(z.string()),
+});
+/**
+ * Why a connection test stopped, from a closed list.
+ *
+ * **Closed because the alternative leaks.** The natural implementation of a
+ * diagnostic is to show what the server said, and what the server said is a
+ * string this product did not write — a proxy's error page, a transport
+ * library's message, a response body. Any of those can carry a URL, a header, or
+ * a fragment of the credential that produced them. A reason from this list
+ * carries none of that and is enough to act on, which is the whole bargain.
+ */
+export const MCP_CONNECTION_FAILURES = [
+    /** The endpoint answered, and refused the credential. */
+    "unauthorized",
+    /** Nothing answered, or what answered was not this endpoint. */
+    "unreachable",
+    /** It answered, but not in a way an MCP client could complete. */
+    "protocol",
+    /** It listed tools, and they are not the ones this credential authorizes. */
+    "mismatch",
+];
+/**
+ * How long something took, coarsely.
+ *
+ * A duration recorded to the millisecond is a fingerprint: repeated across a
+ * small population it distinguishes one member's connection from another's. The
+ * question an activation fact answers is "was this fast enough to feel like it
+ * worked", and a bucket answers it.
+ */
+export const MCP_ACTIVATION_DURATIONS = [
+    "under_1s",
+    "under_5s",
+    "under_30s",
+    "over_30s",
+];
+/** The bucket a measured duration falls in. */
+export function activationDuration(elapsedMs) {
+    if (elapsedMs < 1_000)
+        return "under_1s";
+    if (elapsedMs < 5_000)
+        return "under_5s";
+    if (elapsedMs < 30_000)
+        return "under_30s";
+    return "over_30s";
+}
+/**
+ * What is recorded when somebody connects a client, and the only thing that is.
+ *
+ * **Every field is drawn from a closed set, and that is the point rather than a
+ * convenience.** There is no free-text field, no identifier, no address and no
+ * measurement finer than a bucket, so an event of this shape cannot carry an
+ * account, an organization, a project, an OAuth URL, a token, a destination or a
+ * payload however carelessly it is constructed. The project specification asks
+ * for activation evidence containing "durations and coarse outcomes, never
+ * callback bodies, secrets, tenant identifiers, or customer payloads"; a schema
+ * that admits only those is how that becomes a property instead of a promise.
+ *
+ * `client` is validated against the catalog rather than typed as a string, so a
+ * client nobody has walked cannot appear in activation data as though it had.
+ *
+ * **Strict, not merely typed, and a test is why.** An ordinary object schema
+ * *strips* a field it does not know, which would have made an emitter that added
+ * `project` look like it was recording one while the field silently vanished.
+ * Stripping is safe and dishonest: the caller believes something is being
+ * recorded that is not, and nothing ever tells them. "Closed" has to mean the
+ * schema refuses what it does not recognise, so the mistake surfaces where it
+ * was made.
+ */
+export const mcpActivationEventSchema = z.strictObject({
+    /** Which of the two named authentication modes was used. */
+    authKind: z.enum(["oauth", "api-key"]),
+    /** Every step, and what it did. */
+    checks: z.record(z.enum(MCP_CONNECTION_CHECKS), z.enum(MCP_CONNECTION_OUTCOMES)),
+    /** The catalog id of the client, checked against the catalog by the emitter. */
+    client: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/u),
+    duration: z.enum(MCP_ACTIVATION_DURATIONS),
+    /** Present only when something stopped, and drawn from a closed list. */
+    failure: z.enum(MCP_CONNECTION_FAILURES).optional(),
+    type: z.literal("mcp.connection_test"),
+});

package/dist/oauth.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",
         });
     }
 });