@vidofy/mcp 0.1.0

package/dist/oauth/ratelimit.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Rate limiting for the unauthenticated OAuth endpoints.
+ *
+ * WHY THIS EXISTS — what one request to /mcp-app/authorize actually costs:
+ *
+ *   • an outbound HTTPS request to a URL THE CALLER CHOSE (client_id is a URL and
+ *     we fetch it), preceded by a DNS lookup, bounded at 2s and 8 KB
+ *   • a socket and its buffers in the same process that serves every MCP tool
+ *   • a Redis key that lives 600 seconds
+ *
+ * And it takes no credential at all. So a loop from one machine turns this server
+ * into three different problems at once: our egress IP hammering a third party
+ * who will rightly block us, a Node process out of sockets while real users wait
+ * for a generation, and Redis filling with pending records nobody will redeem.
+ *
+ * WHO ACTUALLY CALLS /authorize, because it decides the shape of the limit:
+ * the USER'S BROWSER, not the AI host's servers. That is not an inference from
+ * the probe log — it is the authorization-code flow: the endpoint carries `state`
+ * and ends at a consent screen the person has to read, which a server-to-server
+ * caller cannot complete. The measured chain agrees (the discovery documents and
+ * the first POST /mcp-app come from Anthropic's cloud; the authorize redirect does
+ * not). So a per-IP bucket is a per-USER bucket here, and the shared-egress worry
+ * that would make per-IP limiting wrong for a machine-to-machine endpoint does not
+ * apply.
+ *
+ * A FIXED WINDOW, not a sliding one. It lets a caller spend the whole budget at
+ * the end of one window and again at the start of the next — twice the nominal
+ * rate across a window boundary — which is the known cost of the cheap algorithm
+ * and is irrelevant at these limits. What it buys is an EXACT `Retry-After`:
+ * seconds until this window resets, computed rather than guessed, which is what
+ * the Partners API already does (see its Retry-After note). A sliding window
+ * cannot answer that question honestly.
+ */
+export interface RateVerdict {
+    allowed: boolean;
+    /** Seconds until the window resets. Exact, not advisory. */
+    retryAfter: number;
+    /** How many hits are in this window, including this one. */
+    count: number;
+}
+/**
+ * Count one hit against a bucket.
+ *
+ * @param bucket     Anything that identifies the caller for this limit, e.g.
+ *                   `authorize:ip:1.2.3.4`. Hashed into the key as-is, so callers
+ *                   must not put anything unbounded in it.
+ * @param limit      Hits allowed per window.
+ * @param windowSec  Window length.
+ *
+ * FAILS CLOSED on a Redis error, and that is deliberate rather than defensive
+ * habit: every endpoint this guards needs Redis to do its job anyway — /authorize
+ * cannot park a pending record without it — so a Redis outage means the request was
+ * going to fail regardless. Refusing early with an honest message beats doing the
+ * expensive outbound fetch first and failing after. The alternative, failing open,
+ * would remove the limiter precisely when the system is least able to absorb a
+ * flood.
+ */
+export declare function hitLimit(bucket: string, limit: number, windowSec: number): Promise<RateVerdict>;
+/** Starts of the flow, per IP. */
+export declare const AUTHORIZE_PER_IP: {
+    limit: number;
+    windowSec: number;
+};
+/**
+ * Starts of the flow per client_id, across all IPs.
+ *
+ * The second layer, and the one that survives a distributed attacker: an attack
+ * from a thousand addresses defeats a per-IP limit entirely, but every request
+ * still has to name a client_id, and it is the client_id that drives the outbound
+ * fetch this endpoint exists to protect. Deliberately much higher than the per-IP
+ * limit — claude.ai is ONE client_id for every one of our users, so this bucket
+ * must never be the thing that throttles legitimate traffic.
+ *
+ * It is not a complete answer on its own: an attacker rotating client_id values
+ * gets a fresh bucket each time. What stops THAT is the concurrency cap on the
+ * fetch itself, in clients.ts — a limit on how many outbound requests can be in
+ * flight, which no amount of key rotation gets around.
+ */
+export declare const AUTHORIZE_PER_CLIENT: {
+    limit: number;
+    windowSec: number;
+};
+/** The consent hand-off. Cheap (one Redis read) but not free, and unauthenticated. */
+export declare const DECIDE_PER_IP: {
+    limit: number;
+    windowSec: number;
+};
+/** The code exchange. One per completed flow; a flood here is guessing codes. */
+export declare const TOKEN_PER_IP: {
+    limit: number;
+    windowSec: number;
+};

package/dist/oauth/ratelimit.js

@@ -0,0 +1,116 @@
+/**
+ * Rate limiting for the unauthenticated OAuth endpoints.
+ *
+ * WHY THIS EXISTS — what one request to /mcp-app/authorize actually costs:
+ *
+ *   • an outbound HTTPS request to a URL THE CALLER CHOSE (client_id is a URL and
+ *     we fetch it), preceded by a DNS lookup, bounded at 2s and 8 KB
+ *   • a socket and its buffers in the same process that serves every MCP tool
+ *   • a Redis key that lives 600 seconds
+ *
+ * And it takes no credential at all. So a loop from one machine turns this server
+ * into three different problems at once: our egress IP hammering a third party
+ * who will rightly block us, a Node process out of sockets while real users wait
+ * for a generation, and Redis filling with pending records nobody will redeem.
+ *
+ * WHO ACTUALLY CALLS /authorize, because it decides the shape of the limit:
+ * the USER'S BROWSER, not the AI host's servers. That is not an inference from
+ * the probe log — it is the authorization-code flow: the endpoint carries `state`
+ * and ends at a consent screen the person has to read, which a server-to-server
+ * caller cannot complete. The measured chain agrees (the discovery documents and
+ * the first POST /mcp-app come from Anthropic's cloud; the authorize redirect does
+ * not). So a per-IP bucket is a per-USER bucket here, and the shared-egress worry
+ * that would make per-IP limiting wrong for a machine-to-machine endpoint does not
+ * apply.
+ *
+ * A FIXED WINDOW, not a sliding one. It lets a caller spend the whole budget at
+ * the end of one window and again at the start of the next — twice the nominal
+ * rate across a window boundary — which is the known cost of the cheap algorithm
+ * and is irrelevant at these limits. What it buys is an EXACT `Retry-After`:
+ * seconds until this window resets, computed rather than guessed, which is what
+ * the Partners API already does (see its Retry-After note). A sliding window
+ * cannot answer that question honestly.
+ */
+import { redisClient } from './store.js';
+/**
+ * `cache:` — and the prefix differs from `mcp_oauth:` on purpose.
+ *
+ * The pending records deliberately avoid `cache:` because the admin "Clear cache"
+ * button would destroy an authorization that exists nowhere else (see store.ts).
+ * A rate-limit counter is the opposite: it is safe to lose. Clearing it just
+ * refills everyone's budget, and the platform's own convention puts rate limits
+ * under `cache:` for exactly that reason, stating the trade-off outright.
+ * Kept visually distinct from the pending keys so nobody
+ * reading a Redis dump mistakes one for the other.
+ */
+const PREFIX = 'cache:mcp:rl';
+/**
+ * Count one hit against a bucket.
+ *
+ * @param bucket     Anything that identifies the caller for this limit, e.g.
+ *                   `authorize:ip:1.2.3.4`. Hashed into the key as-is, so callers
+ *                   must not put anything unbounded in it.
+ * @param limit      Hits allowed per window.
+ * @param windowSec  Window length.
+ *
+ * FAILS CLOSED on a Redis error, and that is deliberate rather than defensive
+ * habit: every endpoint this guards needs Redis to do its job anyway — /authorize
+ * cannot park a pending record without it — so a Redis outage means the request was
+ * going to fail regardless. Refusing early with an honest message beats doing the
+ * expensive outbound fetch first and failing after. The alternative, failing open,
+ * would remove the limiter precisely when the system is least able to absorb a
+ * flood.
+ */
+export async function hitLimit(bucket, limit, windowSec) {
+    const now = Math.floor(Date.now() / 1000);
+    const windowIndex = Math.floor(now / windowSec);
+    const retryAfter = (windowIndex + 1) * windowSec - now;
+    const key = `${PREFIX}:${bucket}:${windowIndex}`;
+    try {
+        const client = await redisClient();
+        const count = await client.incr(key);
+        /* Expire only on the first hit. Re-setting it on every hit would turn the
+           fixed window into a sliding one that never resets under sustained load,
+           so a blocked caller could never recover. */
+        if (count === 1)
+            await client.expire(key, windowSec + 1);
+        return { allowed: count <= limit, retryAfter, count };
+    }
+    catch {
+        return { allowed: false, retryAfter: windowSec, count: -1 };
+    }
+}
+/* ── the limits ──────────────────────────────────────────────────────────────
+ *
+ * Chosen against what a HUMAN does, then multiplied generously, because the cost
+ * of being wrong is asymmetric: too loose still stops the flood, too tight locks a
+ * real person out of connecting their account with no way to tell why.
+ *
+ * A person connecting a client does this ONCE. Twice if they make a mistake and
+ * start again. Ten times in a minute is already someone testing; thirty is not a
+ * person. An attacker needs thousands per minute for any of the three costs above
+ * to matter.
+ */
+/** Starts of the flow, per IP. */
+export const AUTHORIZE_PER_IP = { limit: 30, windowSec: 60 };
+/**
+ * Starts of the flow per client_id, across all IPs.
+ *
+ * The second layer, and the one that survives a distributed attacker: an attack
+ * from a thousand addresses defeats a per-IP limit entirely, but every request
+ * still has to name a client_id, and it is the client_id that drives the outbound
+ * fetch this endpoint exists to protect. Deliberately much higher than the per-IP
+ * limit — claude.ai is ONE client_id for every one of our users, so this bucket
+ * must never be the thing that throttles legitimate traffic.
+ *
+ * It is not a complete answer on its own: an attacker rotating client_id values
+ * gets a fresh bucket each time. What stops THAT is the concurrency cap on the
+ * fetch itself, in clients.ts — a limit on how many outbound requests can be in
+ * flight, which no amount of key rotation gets around.
+ */
+export const AUTHORIZE_PER_CLIENT = { limit: 600, windowSec: 60 };
+/** The consent hand-off. Cheap (one Redis read) but not free, and unauthenticated. */
+export const DECIDE_PER_IP = { limit: 60, windowSec: 60 };
+/** The code exchange. One per completed flow; a flood here is guessing codes. */
+export const TOKEN_PER_IP = { limit: 60, windowSec: 60 };
+//# sourceMappingURL=ratelimit.js.map

package/dist/oauth/store.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The state an authorization flow leaves behind between requests.
+ *
+ * Two short-lived records, both in Redis:
+ *
+ *   pending   /authorize → the consent page → back        (the user has not decided yet)
+ *   code      the redirect to the client → /token          (a one-time authorization code)
+ *
+ * WHY REDIS AND NOT THIS PROCESS'S MEMORY
+ * ---------------------------------------
+ * Owner decision 2026-09-12, and it buys two things memory cannot:
+ *
+ *   1. It survives a restart. A Map would mean every deploy cancels whoever is
+ *      mid-sign-in, and they would see a failure with no cause.
+ *   2. PHP can read and write it. The consent screen lives on vidofy.ai because
+ *      that is where the session cookie is — so approval is recorded by a
+ *      different language in a different process. Shared storage is what lets
+ *      that happen without inventing a signed side-channel between them.
+ *
+ * It is also how the rest of the project already works, which matters more than
+ * elegance: one place to look when something is stuck.
+ *
+ * KEY NAMING — deliberately NOT under `cache:`
+ * --------------------------------------------
+ * The platform's convention is that every cache key starts with `cache:` so an
+ * operator's "Clear cache" action can wipe them with one SCAN. These keys must
+ * NOT carry that prefix, for the same reason the platform exempts its other
+ * write-once secrets. They are not a copy of anything. A pending
+ * authorization exists ONLY here, and an authorization code is a single-use
+ * secret with no source to rebuild it from. An admin pressing Clear Cache while
+ * someone is signing in would destroy it, and the user would be bounced back to
+ * their client with an error nobody could explain.
+ *
+ * So: `mcp_oauth:pending:<id>` and `mcp_oauth:code:<code>`, alongside
+ * `mcp_flash:` which is there for the same reason.
+ *
+ * ⚠ AND THAT PROTECTS THESE KEYS FROM *ONE* ACTION, NOT FROM AN OPERATOR. There
+ * is a second, coarser one that flushes Redis outright. That erases every
+ * database, so it takes `mcp_oauth:` with it along with every session — which is
+ * why its own confirmation warns that all users are signed out. The paragraph
+ * above is about the prefix-scoped clear and was true of it; read alone it
+ * implied a safety these keys do not have.
+ *
+ * The consequence is small and worth stating so nobody hunts it: an admin
+ * pressing that button during someone's consent flow ends that flow with an
+ * error, and the user starts again. A ten-minute window, not a lost credential.
+ */
+import { type RedisClientType } from 'redis';
+/** An authorization request, parked while the user decides. */
+export interface PendingAuthorization {
+    clientId: string;
+    clientName: string;
+    redirectUri: string;
+    codeChallenge: string;
+    /** The resource the token will be bound to — RFC 8707, sent by both hosts. */
+    resource: string;
+    scope: string;
+    /** Echoed back to the client untouched; absent when the client sent none. */
+    state: string | null;
+    /** Consent-screen language hint. ChatGPT sends it, Claude does not. */
+    uiLocales: string | null;
+    createdAt: number;
+    decision?: 'allow' | 'deny';
+    /** The approving account. 0 on deny. */
+    userId?: number;
+    decidedAt?: number;
+    /** The minted `vmt_` token — see IssuedCode.rawToken. Present only on allow. */
+    rawToken?: string;
+    tokenRowId?: number;
+}
+/** An issued authorization code, waiting to be exchanged exactly once. */
+export interface IssuedCode {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    resource: string;
+    scope: string;
+    /** Who approved it. The whole point of the flow. */
+    userId: number;
+    /**
+     * The `vmt_` token itself, minted by PHP at consent time.
+     *
+     * It travels here rather than being created at /token because
+     * The site owns the credential format and the row, and a second
+     * implementation in TypeScript would be a second definition of one
+     * credential. Same pattern as `mcp_flash:` on the tokens page.
+     * Lives at most CODE_TTL_SEC, and the
+     * record is destroyed by GETDEL the moment it is exchanged.
+     */
+    rawToken: string;
+    /** The row id, so a failed exchange can be traced back to what was created. */
+    tokenRowId: number;
+}
+/**
+ * The same connection, for code in this folder that is not about pending records.
+ *
+ * Exported for the rate limiter, which needs Redis and must not open a second
+ * connection to get it: two clients means two reconnect loops, two error handlers
+ * and twice the file descriptors, for one process that already has one working
+ * client. The `.env` reading and the NOAUTH problem below are also things a second
+ * connection would have to get right a second time.
+ */
+export declare function redisClient(): Promise<RedisClientType>;
+export declare function savePending(p: Omit<PendingAuthorization, 'createdAt'>): Promise<string>;
+/**
+ * Read a parked request.
+ *
+ * Returns null when it is missing OR expired — the two are indistinguishable and
+ * should be: the caller's answer is the same, and telling a caller which one it
+ * was lets them probe for ids that exist.
+ */
+export declare function readPending(id: string): Promise<PendingAuthorization | null>;
+export declare function deletePending(id: string): Promise<void>;
+/**
+ * Read a parked request and destroy it in ONE step.
+ *
+ * The same GETDEL reasoning as consumeCode, for the same reason: an approved
+ * request is worth exactly one authorization code. With a read followed by a
+ * delete, two simultaneous hits on /authorize/decide both see the approval
+ * before either removes it, and two codes come out of one consent — which
+ * multiplies a single "Allow" into more grants than the user agreed to.
+ */
+export declare function consumePending(id: string): Promise<PendingAuthorization | null>;
+export declare function issueCode(data: IssuedCode): Promise<string>;
+/**
+ * Consume a code — read it and destroy it in ONE atomic step.
+ *
+ * GETDEL, not GET-then-DEL. With two commands, two simultaneous exchanges of the
+ * same stolen code both read it before either deletes it, and both get a token:
+ * the single-use rule becomes a race. OAuth 2.1 requires the code be usable once,
+ * and this is where that is enforced.
+ */
+export declare function consumeCode(code: string): Promise<IssuedCode | null>;
+/** Close the connection — for tests and a clean shutdown. */
+export declare function closeStore(): Promise<void>;

package/dist/oauth/store.js

@@ -0,0 +1,277 @@
+/**
+ * The state an authorization flow leaves behind between requests.
+ *
+ * Two short-lived records, both in Redis:
+ *
+ *   pending   /authorize → the consent page → back        (the user has not decided yet)
+ *   code      the redirect to the client → /token          (a one-time authorization code)
+ *
+ * WHY REDIS AND NOT THIS PROCESS'S MEMORY
+ * ---------------------------------------
+ * Owner decision 2026-09-12, and it buys two things memory cannot:
+ *
+ *   1. It survives a restart. A Map would mean every deploy cancels whoever is
+ *      mid-sign-in, and they would see a failure with no cause.
+ *   2. PHP can read and write it. The consent screen lives on vidofy.ai because
+ *      that is where the session cookie is — so approval is recorded by a
+ *      different language in a different process. Shared storage is what lets
+ *      that happen without inventing a signed side-channel between them.
+ *
+ * It is also how the rest of the project already works, which matters more than
+ * elegance: one place to look when something is stuck.
+ *
+ * KEY NAMING — deliberately NOT under `cache:`
+ * --------------------------------------------
+ * The platform's convention is that every cache key starts with `cache:` so an
+ * operator's "Clear cache" action can wipe them with one SCAN. These keys must
+ * NOT carry that prefix, for the same reason the platform exempts its other
+ * write-once secrets. They are not a copy of anything. A pending
+ * authorization exists ONLY here, and an authorization code is a single-use
+ * secret with no source to rebuild it from. An admin pressing Clear Cache while
+ * someone is signing in would destroy it, and the user would be bounced back to
+ * their client with an error nobody could explain.
+ *
+ * So: `mcp_oauth:pending:<id>` and `mcp_oauth:code:<code>`, alongside
+ * `mcp_flash:` which is there for the same reason.
+ *
+ * ⚠ AND THAT PROTECTS THESE KEYS FROM *ONE* ACTION, NOT FROM AN OPERATOR. There
+ * is a second, coarser one that flushes Redis outright. That erases every
+ * database, so it takes `mcp_oauth:` with it along with every session — which is
+ * why its own confirmation warns that all users are signed out. The paragraph
+ * above is about the prefix-scoped clear and was true of it; read alone it
+ * implied a safety these keys do not have.
+ *
+ * The consequence is small and worth stating so nobody hunts it: an admin
+ * pressing that button during someone's consent flow ends that flow with an
+ * error, and the user starts again. A ten-minute window, not a lost credential.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createClient } from 'redis';
+/** How long a user has to finish the consent screen. */
+const PENDING_TTL_SEC = 600;
+/**
+ * How long the client has to exchange the code.
+ *
+ * OAuth 2.1 says a code SHOULD be short-lived and single-use, and recommends a
+ * maximum of 10 minutes; 60 seconds is enough for a redirect and one POST, and
+ * every second beyond that is a window for a leaked code to be replayed.
+ */
+const CODE_TTL_SEC = 60;
+const PREFIX = 'mcp_oauth';
+let client = null;
+/**
+ * The shared connection, opened on first use.
+ *
+ * `redis` reconnects on its own; what it does NOT do is queue commands forever
+ * while down, so a caller still has to handle a rejection — see the note on
+ * readPending.
+ */
+/**
+ * The site's `.env`, parsed once — or an empty object when there is none.
+ *
+ * Deliberately minimal: `KEY=value`, `#` comments, optional surrounding quotes.
+ * It is not a dotenv replacement and must not become one; the site's own parser
+ * is the authority on this file's format, and anything it supports that this
+ * does not is a reason to pass the value through the real environment instead.
+ *
+ * Found by walking UP from this module rather than from `process.cwd()`, because
+ * the working directory depends on who started the process — a manager, a shell
+ * in `vidofy-mcp/`, or a shell in the repo root — while the module's own position
+ * relative to the repo never changes. `VIDOFY_ENV_FILE` overrides it outright for
+ * a deployment that puts the file somewhere else.
+ */
+let cachedFileEnv = null;
+function siteEnvFile() {
+    if (cachedFileEnv !== null)
+        return cachedFileEnv;
+    cachedFileEnv = {};
+    const explicit = (process.env['VIDOFY_ENV_FILE'] ?? '').trim();
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/oauth → dist → vidofy-mcp → repo root. Four, to survive src/ vs dist/.
+    const candidates = explicit !== ''
+        ? [explicit]
+        : [1, 2, 3, 4].map((up) => join(here, ...Array(up).fill('..'), '.env'));
+    for (const path of candidates) {
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue; // absent is normal — the npm package has no .env
+        }
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '' || trimmed.startsWith('#'))
+                continue;
+            const eq = trimmed.indexOf('=');
+            if (eq <= 0)
+                continue;
+            const k = trimmed.slice(0, eq).trim();
+            let v = trimmed.slice(eq + 1).trim();
+            if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+                v = v.slice(1, -1);
+            }
+            cachedFileEnv[k] = v;
+        }
+        break;
+    }
+    return cachedFileEnv;
+}
+/**
+ * The same connection, for code in this folder that is not about pending records.
+ *
+ * Exported for the rate limiter, which needs Redis and must not open a second
+ * connection to get it: two clients means two reconnect loops, two error handlers
+ * and twice the file descriptors, for one process that already has one working
+ * client. The `.env` reading and the NOAUTH problem below are also things a second
+ * connection would have to get right a second time.
+ */
+export async function redisClient() {
+    return await redis();
+}
+async function redis() {
+    if (client !== null && client.isOpen)
+        return client;
+    /* Where the connection details come from, in order: the process environment
+     * under `VIDOFY_REDIS_*`, then under the site's own `REDIS_*`, then the site's
+     * `.env` FILE.
+     *
+     * That third source is the one that matters, and it was missing. Only the
+     * `VIDOFY_`-prefixed variables were read, and they appear in no deploy artifact
+     * anywhere — no process-manager config, no unit file, not `.env`. The
+     * first fix for that read `REDIS_*` too, which looked right and was still
+     * incomplete: **Node does not read `.env`.** That file is parsed by the
+     * site's own loader, so `process.env.REDIS_PASSWORD` is empty unless a
+     * human happened to export it in the shell that started this process.
+     *
+     * And it is not a production-only problem, which is what the first version of
+     * this comment assumed. Measured 2026-09-13: local Redis answers
+     * `NOAUTH Authentication required` without a password. So with none of these
+     * variables exported, every call here fails — locally too — and /authorize
+     * answers a bare 500 with no explanation.
+     *
+     * Reading the file is done here rather than by adding dotenv: one dependency
+     * for fifteen lines, on a package that also ships to npm as a standalone stdio
+     * server where the file does not exist and Redis is never used at all. Absent
+     * is therefore silent, not an error. */
+    const fileEnv = siteEnvFile();
+    const env = (a, b, fallback) => {
+        const first = (process.env[a] ?? '').trim();
+        if (first !== '')
+            return first;
+        const second = (process.env[b] ?? '').trim();
+        if (second !== '')
+            return second;
+        return (fileEnv[b] ?? '').trim() || fallback;
+    };
+    const host = env('VIDOFY_REDIS_HOST', 'REDIS_HOST', '127.0.0.1');
+    const port = Number(env('VIDOFY_REDIS_PORT', 'REDIS_PORT', '6379'));
+    const password = env('VIDOFY_REDIS_PASSWORD', 'REDIS_PASSWORD', '');
+    /* The same logical database the site uses. Sharing it is intentional: the
+       site reads these keys, and a different database would mean the consent
+       page writing where this process never looks. */
+    const database = Number(env('VIDOFY_REDIS_DB', 'REDIS_DB', '1'));
+    const c = createClient({
+        socket: { host, port },
+        ...(password !== '' ? { password } : {}),
+        database,
+    });
+    /* Without a listener, an error event on a node-redis client is an unhandled
+       'error' and takes the process down — which would turn a Redis blip into an
+       outage of every tool, not just the ones that need storage. */
+    c.on('error', () => { });
+    await c.connect();
+    client = c;
+    return c;
+}
+/** 32 bytes of URL-safe randomness — the id and code format. */
+function token() {
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(32)))
+        .toString('base64url');
+}
+/* ── pending authorizations ───────────────────────────────────────────────── */
+export async function savePending(p) {
+    const id = token();
+    const c = await redis();
+    await c.set(`${PREFIX}:pending:${id}`, JSON.stringify({ ...p, createdAt: Date.now() }), {
+        expiration: { type: 'EX', value: PENDING_TTL_SEC },
+    });
+    return id;
+}
+/**
+ * Read a parked request.
+ *
+ * Returns null when it is missing OR expired — the two are indistinguishable and
+ * should be: the caller's answer is the same, and telling a caller which one it
+ * was lets them probe for ids that exist.
+ */
+export async function readPending(id) {
+    const raw = await (await redis()).get(`${PREFIX}:pending:${id}`);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function deletePending(id) {
+    await (await redis()).del(`${PREFIX}:pending:${id}`);
+}
+/**
+ * Read a parked request and destroy it in ONE step.
+ *
+ * The same GETDEL reasoning as consumeCode, for the same reason: an approved
+ * request is worth exactly one authorization code. With a read followed by a
+ * delete, two simultaneous hits on /authorize/decide both see the approval
+ * before either removes it, and two codes come out of one consent — which
+ * multiplies a single "Allow" into more grants than the user agreed to.
+ */
+export async function consumePending(id) {
+    const raw = await (await redis()).getDel(`${PREFIX}:pending:${id}`);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/* ── authorization codes ──────────────────────────────────────────────────── */
+export async function issueCode(data) {
+    const code = token();
+    await (await redis()).set(`${PREFIX}:code:${code}`, JSON.stringify(data), {
+        expiration: { type: 'EX', value: CODE_TTL_SEC },
+    });
+    return code;
+}
+/**
+ * Consume a code — read it and destroy it in ONE atomic step.
+ *
+ * GETDEL, not GET-then-DEL. With two commands, two simultaneous exchanges of the
+ * same stolen code both read it before either deletes it, and both get a token:
+ * the single-use rule becomes a race. OAuth 2.1 requires the code be usable once,
+ * and this is where that is enforced.
+ */
+export async function consumeCode(code) {
+    const raw = await (await redis()).getDel(`${PREFIX}:code:${code}`);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Close the connection — for tests and a clean shutdown. */
+export async function closeStore() {
+    if (client !== null && client.isOpen)
+        await client.quit();
+    client = null;
+}
+//# sourceMappingURL=store.js.map

package/dist/oauth/token.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `POST /mcp-app/token` — the authorization code becomes an access token.
+ *
+ * This is the only place a credential leaves the server, so everything it checks
+ * is a precondition for handing one over:
+ *
+ *   1. the code exists and has not been used   (GETDEL — one code, one token)
+ *   2. the client asking is the client the code was issued to
+ *   3. the redirect_uri matches the one bound to the code
+ *   4. PKCE: SHA256(code_verifier) equals the challenge recorded at /authorize
+ *
+ * PKCE IS THE WHOLE PROTECTION HERE
+ * ---------------------------------
+ * The code travels through the user's browser — in a URL, through history, past
+ * whatever extensions are installed. Anyone who captures it could exchange it,
+ * and the client authenticates with `none` (a public client has no secret to
+ * prove itself with). What stops the exchange is that the thief does not have
+ * the verifier: it never left the client. So this check is not defence in depth,
+ * it is the door.
+ *
+ * WHY THERE IS NO TOKEN GENERATION IN THIS FILE
+ * ---------------------------------------------
+ * The `vmt_` token was minted by the site when the user approved, and rides in
+ * the code record. The site owns the credential format, the hash, the scope and
+ * the expiry; a second implementation here would be a second definition of one
+ * credential.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function handleToken(req: IncomingMessage, res: ServerResponse): Promise<void>;