@vidofy/mcp 0.1.0

package/dist/oauth/authorize.js

@@ -0,0 +1,275 @@
+/**
+ * `GET /mcp-app/authorize` — the protocol half of the authorization endpoint.
+ *
+ * It does everything that does not need to know who the user is: identify the
+ * calling client, check what it asked for, park the request, and hand the
+ * browser to the consent screen. Deciding is the user's half, and that lives at
+ * /en/oauth/consent on the site itself, because the session cookie is
+ * host-scoped to vidofy.ai by the site's session layer, and this process
+ * cannot read it.
+ *
+ * TWO URLS, ONE FLOW — and they are named differently on purpose:
+ *
+ *   /mcp-app/authorize   machine-facing. What `authorization_endpoint` advertises.
+ *   /en/oauth/consent    human-facing. Product-neutral, so the CLI or any later
+ *                        client reaches the same screen (owner, 2026-09-12).
+ *
+ * Calling both "authorize" was the first draft and would have cost somebody an
+ * hour six months from now.
+ *
+ * THE ERROR RULE THAT MATTERS
+ * ---------------------------
+ * OAuth 2.1 splits failures in two, and the split is a security boundary rather
+ * than a style:
+ *
+ *   • client_id or redirect_uri is bad  → answer HERE, never redirect. Redirecting
+ *     to a URI we have not validated IS the open redirect.
+ *   • anything else is wrong            → redirect to the VALIDATED redirect_uri
+ *     with `error` and `state`, because the client is waiting there and a page
+ *     served by us is a dead end it cannot recover from.
+ */
+import { fetchClientMetadata, redirectUriAllowed, ClientError } from './clients.js';
+import { savePending, readPending, consumePending, issueCode } from './store.js';
+import { resolveBaseUrl } from '../config.js';
+/** Where the human decides. Product-neutral — see the header. */
+const CONSENT_PATH = '/en/oauth/consent';
+/**
+ * The only scope this server grants, as the client sees it.
+ *
+ * It must stay the name advertised in `scopes_supported` in the
+ * authorization-server document (http.ts) and in the 401's `scope` parameter —
+ * three places, one string. The credential's INTERNAL scope is a different name
+ * because that one is what the server enforces per endpoint; they are
+ * deliberately not the same value and neither is derived from the other.
+ */
+const GRANTED_SCOPE = 'vidofy.generate';
+/** Fail before the redirect_uri is trusted: answer directly. */
+function failHere(res, status, error, description) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error, error_description: description }, null, 2));
+}
+/** Fail after it is trusted: send the client its error, with state intact. */
+function failToClient(res, redirectUri, error, description, state) {
+    const u = new URL(redirectUri);
+    u.searchParams.set('error', error);
+    u.searchParams.set('error_description', description);
+    if (state !== null)
+        u.searchParams.set('state', state);
+    res.writeHead(302, { location: u.href });
+    res.end();
+}
+/**
+ * @param canonicalResource This server's own resource identifier — the value
+ *        both hosts send as `resource`. A request naming anything else is asking
+ *        us to mint a token for an audience we do not serve.
+ */
+export async function handleAuthorize(res, url, canonicalResource, opts = {}) {
+    const q = url.searchParams;
+    const get = (k) => {
+        const v = q.get(k);
+        return v === null || v.trim() === '' ? null : v.trim();
+    };
+    const clientId = get('client_id');
+    const redirectUri = get('redirect_uri');
+    const state = get('state');
+    if (clientId === null) {
+        failHere(res, 400, 'invalid_request', 'client_id is required.');
+        return;
+    }
+    if (redirectUri === null) {
+        failHere(res, 400, 'invalid_request', 'redirect_uri is required.');
+        return;
+    }
+    /* Identify the client from its own metadata document, and only then trust
+       the redirect_uri it sent. Both checks must pass before a single redirect
+       happens — that ordering is the whole protection. */
+    let client;
+    try {
+        client = await fetchClientMetadata(clientId, {
+            ...(opts.allowPrivateClients === true ? { allowPrivate: true } : {}),
+        });
+    }
+    catch (err) {
+        failHere(res, 400, 'invalid_client', err instanceof ClientError ? err.message : 'client_id could not be resolved.');
+        return;
+    }
+    if (!redirectUriAllowed(client, redirectUri)) {
+        failHere(res, 400, 'invalid_request', 'redirect_uri is not listed in the client_id document.');
+        return;
+    }
+    // ── From here the redirect_uri is trusted, so errors go back to the client ──
+    if (get('response_type') !== 'code') {
+        failToClient(res, redirectUri, 'unsupported_response_type', 'Only response_type=code is supported.', state);
+        return;
+    }
+    /* PKCE is mandatory in OAuth 2.1 and we advertise S256 alone. `plain` exists
+       in the RFC for clients that cannot hash; no MCP client is one, and
+       accepting it would mean a challenge an eavesdropper can replay. */
+    const codeChallenge = get('code_challenge');
+    if (codeChallenge === null) {
+        failToClient(res, redirectUri, 'invalid_request', 'code_challenge is required.', state);
+        return;
+    }
+    if (get('code_challenge_method') !== 'S256') {
+        failToClient(res, redirectUri, 'invalid_request', 'code_challenge_method must be S256.', state);
+        return;
+    }
+    /* RFC 8707. Measured 2026-09-12: claude.ai and ChatGPT BOTH send it, so this
+       is the live path and not a defensive branch. The token we eventually issue
+       is bound to this value; a request naming another resource is asking for a
+       token we must not mint, and `invalid_target` is the RFC's own code for it.
+       Absent is tolerated — the spec puts the MUST on clients, and refusing a
+       compliant-enough client would break it for no gain when we bind to our own
+       resource anyway. */
+    const resource = get('resource');
+    if (resource !== null && resource !== canonicalResource) {
+        failToClient(res, redirectUri, 'invalid_target', 'resource does not identify this server.', state);
+        return;
+    }
+    const id = await savePending({
+        clientId,
+        clientName: client.clientName,
+        redirectUri,
+        codeChallenge,
+        resource: canonicalResource,
+        /* The GRANTED scope, fixed — not the requested one.
+         *
+         * This used to be `get('scope') ?? 'vidofy.generate'`, so whatever string
+         * the client asked for was stored and then echoed back from /token as
+         * though it had been granted. It never was: the server mints exactly
+         * one scope (`generate_read`, its default) and the router enforces
+         * that and nothing else. A client asking for `admin` would have been told
+         * `admin` and given `generate_read` — a lie in a protocol field clients are
+         * entitled to believe.
+         *
+         * When more than one scope exists, the requested value gets intersected
+         * with what we are willing to grant HERE, and the result is what is stored.
+         * Until then there is one answer and this is it. */
+        scope: GRANTED_SCOPE,
+        state,
+        // ChatGPT sends ui_locales=en-US, Claude sends none. Carried through so
+        // the consent screen can honour it; nothing reads it yet.
+        uiLocales: get('ui_locales'),
+    });
+    /* The consent screen lives on the SITE, not here — a different origin in
+       development and the same one in production. Built from
+       VIDOFY_API_BASE through the same validator the credential path uses, so a
+       hostile value cannot send the user somewhere else. */
+    const consent = new URL(CONSENT_PATH, resolveBaseUrl());
+    consent.searchParams.set('request', id);
+    res.writeHead(302, { location: consent.href });
+    res.end();
+}
+/**
+ * `GET /mcp-app/authorize/decide?request=<id>` — the browser coming back from
+ * the consent page.
+ *
+ * Turns a recorded decision into the OAuth response the waiting client expects:
+ * a code, or `access_denied`.
+ *
+ * WHAT IT TRUSTS, AND WHY
+ * -----------------------
+ * Everything comes from the stored record; nothing from this request except the
+ * id. In particular the redirect_uri is the one /authorize validated against the
+ * client's metadata document minutes ago — reading it from the query here would
+ * undo that check and hand anyone with a request id a code sent wherever they
+ * like.
+ *
+ * The approving user's identity comes from the record too, written by the
+ * site's consent page after it authenticated the session. This process
+ * cannot verify a session cookie (host-scoped to the site), so the trust
+ * boundary is Redis itself: only the site and this connector can write those
+ * keys, and Redis is not reachable from outside the host.
+ */
+export async function handleAuthorizeDecide(res, url) {
+    const id = url.searchParams.get('request');
+    if (id === null || id.trim() === '') {
+        failHere(res, 400, 'invalid_request', 'request is required.');
+        return;
+    }
+    /* READ first. Only a DECIDED record is consumed.
+     *
+     * ⚠ THIS USED TO CONSUME UNCONDITIONALLY, and the comment that stood here
+     * defended it — "one consent is worth exactly one code" — which is true and
+     * was not the whole story. GETDEL ran before anything checked whether a
+     * decision existed, so a hit on this URL with an id and NO approval deleted
+     * the pending record and the old comment shrugged: "the record is already
+     * gone". That is a denial of service on somebody else's sign-in. The id is
+     * not guessable (32 random bytes) but it is not secret either — it sits in
+     * the address bar of the consent page, so it is in browser history, in a
+     * screen share, in a pasted URL. One request, and the user who then clicks
+     * Allow is told their request expired, with nothing anywhere explaining why.
+     *
+     * Found by test/oauth_flow.test.mjs on its first run — this endpoint had no
+     * test at all until then.
+     *
+     * The single-use property is kept exactly: an undecided record is only read,
+     * and a decided one is taken with GETDEL, so two concurrent hits after an
+     * approval still produce one code. Consuming late does not weaken that; it
+     * only stops the undecided case from being destructive. */
+    const peek = await readPending(id.trim());
+    if (peek === null) {
+        failHere(res, 400, 'invalid_request', 'This authorization request has expired or was already completed.');
+        return;
+    }
+    if (peek.decision === undefined) {
+        /* Nobody approved anything: someone reached this URL without passing
+           through the consent page. The record is LEFT ALONE so the real flow can
+           still finish. Answered here rather than redirected — the client is not
+           owed a response to a flow its user never completed. */
+        failHere(res, 400, 'access_denied', 'This request was not approved.');
+        return;
+    }
+    const pending = await consumePending(id.trim());
+    if (pending === null) {
+        /* Lost the race against a concurrent decide, or it expired in the
+           microseconds between the two calls. Either way exactly one caller got
+           it, which is the property that matters. */
+        failHere(res, 400, 'invalid_request', 'This authorization request has expired or was already completed.');
+        return;
+    }
+    if (pending.decision === undefined) {
+        // Cannot happen — the peek above saw one. Fail closed rather than assume.
+        failHere(res, 400, 'access_denied', 'This request was not approved.');
+        return;
+    }
+    /* An approval with no token is an approval we cannot honour: the consent
+       page refuses to record one, so reaching here means the record was
+       tampered with or written by an older build. Treated as a denial rather
+       than issuing a code /token could never fulfil — the client would otherwise
+       show success and then fail. */
+    const rawToken = typeof pending.rawToken === 'string' && pending.rawToken.startsWith('vmt_')
+        ? pending.rawToken
+        : null;
+    if (pending.decision === 'allow' && rawToken === null) {
+        failToClient(res, pending.redirectUri, 'server_error', 'The access token could not be prepared.', pending.state);
+        return;
+    }
+    if (pending.decision !== 'allow' || rawToken === null
+        || typeof pending.userId !== 'number' || pending.userId <= 0) {
+        /* A refusal is a normal OAuth outcome, not an error page: the client is
+           waiting at its redirect_uri and can tell the user plainly. */
+        failToClient(res, pending.redirectUri, 'access_denied', 'The user declined the request.', pending.state);
+        return;
+    }
+    const code = await issueCode({
+        clientId: pending.clientId,
+        redirectUri: pending.redirectUri,
+        codeChallenge: pending.codeChallenge,
+        resource: pending.resource,
+        scope: pending.scope,
+        userId: pending.userId,
+        rawToken,
+        tokenRowId: pending.tokenRowId ?? 0,
+    });
+    const back = new URL(pending.redirectUri);
+    back.searchParams.set('code', code);
+    /* Echoed byte for byte when present, and omitted entirely when not. `state`
+       is the client's own CSRF protection for this flow; altering or inventing
+       one breaks the check it exists for. */
+    if (pending.state !== null)
+        back.searchParams.set('state', pending.state);
+    res.writeHead(302, { location: back.href });
+    res.end();
+}
+//# sourceMappingURL=authorize.js.map

package/dist/oauth/clients.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Who is asking — OAuth client identification by Client ID Metadata Document.
+ *
+ * An MCP client tells us who it is by putting a URL in `client_id` and hosting
+ * its own OAuth metadata there (draft-ietf-oauth-client-id-metadata-document).
+ * We fetch that URL and read the client's name and its permitted redirect_uris.
+ *
+ * WHY ONLY THIS MECHANISM
+ * -----------------------
+ * The spec offers three (Client ID Metadata Documents, pre-registration,
+ * Dynamic Client Registration) and calls DCR "deprecated, retained for backwards
+ * compatibility". We did not take that on faith: the connector advertised BOTH
+ * `registration_endpoint` and `client_id_metadata_document_supported` and logged
+ * what real hosts chose (2026-09-12, through a cloudflared tunnel):
+ *
+ *   claude.ai  client_id = https://claude.ai/oauth/mcp-oauth-client-metadata
+ *   ChatGPT    client_id = https://chatgpt.com/oauth/<per-connector>/client.json
+ *   requests to /register = ZERO, from either
+ *
+ * So DCR is not implemented and `registration_endpoint` is not advertised. When
+ * a client appears that needs it, the log will show the call and we will know.
+ *
+ * ⚠ THIS FETCHES A URL THE CALLER CHOSE
+ * -------------------------------------
+ * `client_id` is attacker-controlled by definition — anyone can start an
+ * authorization request. ChatGPT's is per-connector and unguessable, so we
+ * cannot allow-list known URLs; the document really is arbitrary. That makes
+ * this a server-side request forgery surface: point `client_id` at
+ * http://169.254.169.254/ or http://127.0.0.1:6379/ and the fetch becomes a
+ * probe of our own network.
+ *
+ * The guards below mirror the same rules the site already applies to partner
+ * callback URLs, rather than inventing a second policy. They are reimplemented
+ * rather than called because the site's copy is PHP; where the two could drift,
+ * the site is the reference.
+ */
+import type { LookupAddress, LookupAllOptions, LookupOneOptions } from 'node:dns';
+/** What the authorization flow needs to know about the caller. */
+export interface ClientInfo {
+    /** The URL that identifies it — echoed back as client_id. */
+    clientId: string;
+    /** Display name for the consent screen. Falls back to the host. */
+    clientName: string;
+    /** Every redirect_uri the client says it may use. */
+    redirectUris: string[];
+    /** For the consent screen's "this is who is asking" line. */
+    clientUri: string | null;
+    logoUri: string | null;
+}
+export declare class ClientError extends Error {
+}
+/**
+ * A refusal whose REASON must not reach the caller.
+ *
+ * The split it marks is the whole of the oracle fix, so it is worth stating as a
+ * rule rather than a habit:
+ *
+ *   ClientError        — decided from the caller's own string, with no network
+ *                        touched: not a URL, not https, has credentials, has a
+ *                        fragment, port not allowed. The caller already knows their
+ *                        own URL, so saying why tells them nothing they did not
+ *                        have, and it is exactly what a client developer needs.
+ *
+ *   OpaqueClientError  — decided by what happened when we reached out to a host the
+ *                        CALLER CHOSE: the address rules, the connection, the
+ *                        status, the size, whether the body parsed, whether the
+ *                        document declared what it must.
+ *
+ * Why the second group must be silent, and why that does not cost a legitimate
+ * developer anything: every one of those answers is already available to whoever
+ * owns the host. Their access log shows our request and their own response; their
+ * document is in their hands. They do not need us to tell them it returned 500.
+ *
+ * An attacker probing an internal address has none of that — which is precisely
+ * what made our message valuable to them. `document returned 403` versus
+ * `is not a JSON object` versus `could not be fetched`, over a range of addresses,
+ * is a port scanner with our egress IP and no credential.
+ *
+ * The real reason is logged on our side, always. Nothing is lost, it just stops
+ * being answered to a stranger.
+ */
+export declare class OpaqueClientError extends ClientError {
+}
+/**
+ * The `lookup` hook `net.connect` calls to decide where the socket goes.
+ *
+ * For a HOSTNAME this is the only resolution on the connect path, so the address
+ * checked here is by construction the address connected to — which is what closes
+ * the rebinding window described in assertFetchable. The hostname still travels as
+ * SNI and in the Host header, so TLS and certificate validation are untouched;
+ * pinning by rewriting the URL to an IP would have broken both.
+ *
+ * ⚠ AND IT IS NEVER CALLED FOR AN IP LITERAL. Measured 2026-09-12: a request to
+ * `127.0.0.1` reached ECONNREFUSED without the hook being invoked once, while
+ * `localhost` did invoke it — `net.connect` has nothing to resolve when the host
+ * is already an address, so it skips the hook entirely. An earlier version of this
+ * comment claimed this was "the ONLY place the fetch resolves the host", full
+ * stop, which is false for literals.
+ *
+ * Nothing is exposed by that: a literal is refused in assertFetchable before any
+ * socket opens. But it means the two halves are not interchangeable — literals are
+ * guarded THERE and names are guarded HERE — and a test that only exercises this
+ * function is not testing the literal path at all.
+ *
+ * Fails CLOSED in every ambiguous case: a resolution error, an empty answer, or
+ * ANY blocked address among the answers refuses the whole connection rather than
+ * picking a surviving one. A host that answers with both a public and a private
+ * address has no business being a client_id.
+ *
+ * EXPORTED only so it can be tested directly, and that is not a formality: the
+ * check in assertFetchable cannot be reached past by a test without running a
+ * hostile DNS server, so the only way to prove this hook refuses what it claims
+ * to refuse is to call it. Nothing outside this module should use it.
+ */
+export declare function safeLookup(hostname: string, options: LookupOneOptions | LookupAllOptions, callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void): void;
+/**
+ * Fetch and validate a client's metadata document.
+ *
+ * The public entry point, and the ONLY place the opaque/verbatim policy is applied
+ * — so there is one answer to "what does a stranger learn from a refusal" instead
+ * of one per throw site. Everything below it throws the truth; this decides what
+ * leaves the building, and logs the truth either way.
+ *
+ * @throws ClientError whose message is safe to surface, always.
+ */
+export declare function fetchClientMetadata(clientId: string, opts?: {
+    allowPrivate?: boolean;
+}): Promise<ClientInfo>;
+/**
+ * Is this redirect_uri one the client declared?
+ *
+ * Exact string comparison, which is what OAuth 2.1 requires and what makes the
+ * check worth having: any normalisation (trailing slash, case, added query) is a
+ * place where "close enough" sends the authorization code somewhere the client
+ * never listed.
+ */
+export declare function redirectUriAllowed(client: ClientInfo, redirectUri: string): boolean;