@faable/faable 4.5.4 → 4.6.0

package/dist/lib/UpdateChecker.js

@@ -6,6 +6,7 @@ import { log } from '../log.js';
 
 const CLI_PACKAGE = "@faable/faable";
 const REGISTRY_URL = `https://registry.npmjs.org/${CLI_PACKAGE}/latest`;
+const PACKUMENT_URL = `https://registry.npmjs.org/${CLI_PACKAGE.replace("/", "%2f")}`;
 // Hitting the registry at most once a day keeps the background refresh rare.
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const UPGRADE_FETCH_TIMEOUT_MS = 10_000;
@@ -77,16 +78,21 @@ const spawnBackgroundRefresh = () => {
  */
 const getLatestVersion = async () => {
     try {
-        const res = await fetch(REGISTRY_URL, {
+        // The same (abbreviated) packument `npm install` resolves against, not
+        // `/latest`: for a few minutes after a release the two endpoints
+        // disagree, and offering a version npm can't find yet ends in ETARGET.
+        const res = await fetch(PACKUMENT_URL, {
+            headers: { Accept: "application/vnd.npm.install-v1+json" },
             signal: AbortSignal.timeout(UPGRADE_FETCH_TIMEOUT_MS),
         });
         if (!res.ok)
             return;
         const data = (await res.json());
-        if (data.version) {
-            await writeCache({ last_check: new Date().toISOString(), latest: data.version });
+        const version = data["dist-tags"]?.latest;
+        if (version) {
+            await writeCache({ last_check: new Date().toISOString(), latest: version });
         }
-        return data.version;
+        return version;
     }
     catch {
         return;

package/dist/mcp/http.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { z } from 'zod';
 import { version } from '../config.js';
+import { ALL_SCOPES, AUTH_ISSUER, oauth_enabled, protected_resource_metadata, www_authenticate, looks_like_jwt, verify_access_token, resource_of, permissions_of, permission_of, delegated_token_for, prm_url } from './oauth.js';
 import { run_cli } from './run_cli.js';
 import { tools_for, create_server } from './server.js';
 import { TOOLS } from './tools.js';
@@ -40,8 +41,17 @@ const api_key_of = (req) => {
     if (!key && basic) {
         key = Buffer.from(basic[1], 'base64').toString('utf8').split(':')[0];
     }
-    return key && /^[\w.~+/=-]{8,256}$/.test(key) ? key : null;
+    if (!key)
+        return null;
+    // An OAuth access token (a JWT) is longer than any API key.
+    if (looks_like_jwt(key))
+        return key.length <= 8192 ? key : null;
+    return /^[\w.~+/=-]{8,256}$/.test(key) ? key : null;
 };
+// The tools a JSON-RPC body calls (one message or a batch).
+const calls_in = (body) => (Array.isArray(body) ? body : [body])
+    .filter((m) => m?.method === 'tools/call' && typeof m?.params?.name === 'string')
+    .map((m) => m.params.name);
 // /mcp → {}, /mcp/<project> → { project }; anything else → null.
 const route_of = (pathname) => {
     const m = /^\/mcp(?:\/([^/]+))?\/?$/.exec(pathname);
@@ -52,13 +62,20 @@ const route_of = (pathname) => {
 // The environment of one call: the server's own, minus every credential and
 // context it might carry, plus the caller's key and an empty HOME.
 const SCRUBBED = /^(FAABLE_(TOKEN|API_KEY|PROJECT|AUTH_ACCOUNT|AUTH_URL|ID_TOKEN)|GITHUB_ACTIONS|ACTIONS_ID_TOKEN_.*)$/;
-const child_env = (key, home) => {
+const child_env = (cred, home) => {
     const env = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (!SCRUBBED.test(k))
             env[k] = v;
     }
-    return { ...env, HOME: home, FAABLE_API_KEY: key };
+    const c = typeof cred === 'string' ? { api_key: cred } : cred;
+    return {
+        ...env,
+        HOME: home,
+        ...('api_key' in c
+            ? { FAABLE_API_KEY: c.api_key }
+            : { FAABLE_TOKEN: c.token })
+    };
 };
 // At most `max` children at once.
 const limiter = (max) => {
@@ -77,13 +94,16 @@ const limiter = (max) => {
         }
     };
 };
-const runner_for = (key, limit, entry) => (argv, opts) => limit(async () => {
+const runner_for = (credential, limit, entry) => (argv, opts) => limit(async () => {
+    // Resolved per call, not per request: an OAuth connection trades its
+    // token only when a tool actually runs, never for a tools/list.
+    const cred = await credential();
     const home = await mkdtemp(path.join(os.tmpdir(), 'faable-mcp-'));
     try {
         return await run_cli(argv, {
             ...opts,
             entry,
-            env: child_env(key, home)
+            env: child_env(cred, home)
         });
     }
     finally {
@@ -131,11 +151,24 @@ const catalog = (base = PUBLIC_URL) => ({
     version,
     endpoint: `${base}/mcp`,
     transport: 'streamable-http',
-    auth: {
-        type: 'api-key',
-        header: 'Authorization: Bearer <key>',
-        keys: KEYS_URL
-    },
+    // OAuth first when the server has it on (oauth.ts); an API key always works.
+    auth: oauth_enabled()
+        ? {
+            type: 'oauth',
+            authorization_server: AUTH_ISSUER,
+            protected_resource_metadata: prm_url(base),
+            scopes: ALL_SCOPES,
+            alternative: {
+                type: 'api-key',
+                header: 'Authorization: Bearer <key>',
+                keys: KEYS_URL
+            }
+        }
+        : {
+            type: 'api-key',
+            header: 'Authorization: Bearer <key>',
+            keys: KEYS_URL
+        },
     docs: DOCS_URL,
     tools: TOOLS.map(t => ({
         name: t.name,
@@ -151,7 +184,9 @@ const llms_txt = (base = PUBLIC_URL) => [
     '',
     '> Connects Claude, Cursor and any MCP client to Faable Deploy: read apps, deployments, build and runtime logs, traffic and domains, and deploy — without leaving the editor.',
     '',
-    `Endpoint: ${base}/mcp (Streamable HTTP). Authenticate with a Faable API key: \`Authorization: Bearer <key>\` (create one in the dashboard, project settings → API keys). The key belongs to one project and only acts there.`,
+    oauth_enabled()
+        ? `Endpoint: ${base}/mcp (Streamable HTTP). Sign in with OAuth: an MCP client discovers it from the 401 (\`resource_metadata\`), opens a Faable sign-in and consent screen where the user picks one project and what the agent may do (\`deploy:read\`, \`deploy:deploy\`; \`deploy:write\` is asked for the first time a write tool is called). Or send a Faable API key: \`Authorization: Bearer <key>\` (project settings → API keys). Either way it acts on one project only.`
+        : `Endpoint: ${base}/mcp (Streamable HTTP). Authenticate with a Faable API key: \`Authorization: Bearer <key>\` (create one in the dashboard, project settings → API keys). The key belongs to one project and only acts there.`,
     '',
     `- \`${base}/mcp/<project>\` pins every call to one project.`,
     '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings). Nothing destructive is exposed.',
@@ -197,6 +232,14 @@ const create_http_server = (opts) => {
             if (req.method === 'GET' && url.pathname === '/llms.txt') {
                 return send(res, 200, llms_txt(base), 'text/plain; charset=utf-8');
             }
+            // RFC 9728: at the root and with the resource path inserted (what MCP
+            // clients derive from https://mcp.faable.com/mcp). Only with OAuth on.
+            if (req.method === 'GET' &&
+                /^\/\.well-known\/oauth-protected-resource(\/mcp(\/[^/]+)?)?\/?$/.test(url.pathname)) {
+                if (!oauth_enabled())
+                    return send(res, 404, { error: 'not found' });
+                return send(res, 200, protected_resource_metadata(base));
+            }
             const route = route_of(url.pathname);
             if (!route)
                 return send(res, 404, { error: 'not found', docs: DOCS_URL });
@@ -206,11 +249,32 @@ const create_http_server = (opts) => {
                 return send(res, 405, rpc_error(-32000, 'Method not allowed: this server is stateless, use POST.'));
             }
             const key = api_key_of(req);
-            if (!key) {
-                res.setHeader('www-authenticate', 'Bearer realm="faable"');
+            const unauthorized = (message, error) => {
+                res.setHeader('www-authenticate', oauth_enabled()
+                    ? www_authenticate(base, { error })
+                    : 'Bearer realm="faable"');
                 status = 401;
-                return send(res, 401, rpc_error(-32001, `Send a Faable API key: "Authorization: Bearer <key>". Create one in the dashboard (project settings → API keys): ${KEYS_URL}`));
+                return send(res, 401, rpc_error(-32001, message));
+            };
+            if (!key) {
+                return unauthorized(oauth_enabled()
+                    ? `Connect with your Faable account (your MCP client opens the sign-in), or send a Faable API key: "Authorization: Bearer <key>" (${KEYS_URL}).`
+                    : `Send a Faable API key: "Authorization: Bearer <key>". Create one in the dashboard (project settings → API keys): ${KEYS_URL}`);
             }
+            // A JWT is an OAuth access token (Fase 3); anything else, an API key.
+            let claims;
+            if (looks_like_jwt(key)) {
+                if (!oauth_enabled()) {
+                    return unauthorized(`This server does not accept OAuth tokens yet. Send a Faable API key: ${KEYS_URL}`);
+                }
+                try {
+                    claims = await verify_access_token(key, resource_of(base));
+                }
+                catch (e) {
+                    return unauthorized(`Invalid access token: ${e.message}. Reconnect.`, 'invalid_token');
+                }
+            }
+            const granted = claims ? permissions_of(claims) : undefined;
             let body;
             try {
                 body = await read_body(req);
@@ -218,11 +282,39 @@ const create_http_server = (opts) => {
             catch (e) {
                 return send(res, 400, rpc_error(-32700, e.message));
             }
+            // Step-up (MCP authorization): a tool this connection was not allowed
+            // answers 403 insufficient_scope with the scope it needs, and the
+            // client asks the user for it on the consent screen.
+            if (granted) {
+                const needed = calls_in(body)
+                    .map(name => TOOLS.find(t => t.name === name))
+                    .filter((t) => !!t)
+                    .map(permission_of)
+                    .filter(p => !granted.includes(p));
+                if (needed.length) {
+                    res.setHeader('www-authenticate', www_authenticate(base, {
+                        error: 'insufficient_scope',
+                        scope: [...new Set([...granted, ...needed])]
+                    }));
+                    status = 403;
+                    return send(res, 403, rpc_error(-32001, `This connection was not allowed to ${needed.join(', ')}. Your MCP client will ask you to allow it.`));
+                }
+            }
+            const writes = url.searchParams.get('mode') === 'write';
             const server = create_server({
-                writes: url.searchParams.get('mode') === 'write',
+                writes,
                 readonly: ['1', 'true'].includes(url.searchParams.get('readonly') ?? ''),
-                project: route.project,
-                run: runner_for(key, limit, opts.entry)
+                // An OAuth connection acts on the project the user picked on the
+                // consent screen, whatever the path or the agent say.
+                project: claims?.project ?? route.project,
+                // Its tools are the ones its permissions allow — plus, with
+                // ?mode=write, the writes it may ask for by step-up.
+                allow: granted
+                    ? t => granted.includes(permission_of(t)) || (writes && !!t.write)
+                    : undefined,
+                run: runner_for(claims
+                    ? async () => ({ token: await delegated_token_for(key) })
+                    : async () => ({ api_key: key }), limit, opts.entry)
             });
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
@@ -255,4 +347,4 @@ const serve_http = async (opts) => {
     return server;
 };
 
-export { PUBLIC_URL, api_key_of, catalog, child_env, create_http_server, llms_txt, route_of, serve_http };
+export { PUBLIC_URL, api_key_of, calls_in, catalog, child_env, create_http_server, llms_txt, route_of, serve_http };

package/dist/mcp/oauth.js

@@ -0,0 +1,161 @@
+import { verify, createPublicKey, createHash } from 'node:crypto';
+
+// OAuth on mcp.faable.com (Fase 3 of arch/deploy/mcp-server-faable.md; plan
+// in arch/auth/mcp-oauth.md 3.5). The MCP server is a resource server:
+//
+//   1. the MCP client gets a token from Faable Auth for THIS resource
+//      (aud = https://mcp.faable.com/mcp) after the user allowed it on the
+//      consent screen — permissions and one project;
+//   2. this server checks it (issuer, audience, expiry, signature) and shows
+//      only the tools its permissions allow;
+//   3. for a tool call it trades it at Faable Auth (RFC 8693) for a short
+//      token of its own, `act` = this server, and the CLI child calls the
+//      api with that. The client's token is never passed on (MCP spec:
+//      MUST NOT), and the api refuses it if anyone tries.
+//
+// Off unless the server has its own client credentials
+// (FAABLE_MCP_CLIENT_ID / FAABLE_MCP_CLIENT_SECRET): advertising OAuth before
+// Faable Auth accepts MCP clients would send them into a flow that fails.
+// API keys keep working either way.
+const AUTH_ISSUER = process.env.FAABLE_MCP_AUTH_ISSUER ?? 'https://faable.auth.faable.link';
+const oauth_enabled = () => !!process.env.FAABLE_MCP_CLIENT_ID && !!process.env.FAABLE_MCP_CLIENT_SECRET;
+// What the consent screen asks for on a first connection (Marc, 05-10:
+// reads plus deploy, like the hosted server by default). deploy:write comes
+// by step-up, the first time an agent calls a tool that needs it.
+const DEFAULT_SCOPES = ['deploy:read', 'deploy:deploy'];
+const ALL_SCOPES = [
+    'deploy:read',
+    'deploy:deploy',
+    'deploy:write'
+];
+const DEPLOY_TOOLS = new Set(['deploy_app', 'redeploy', 'cancel_deployment']);
+/** The permission a tool needs — the same split the api enforces. */
+const permission_of = (tool) => DEPLOY_TOOLS.has(tool.name)
+    ? 'deploy:deploy'
+    : tool.write
+        ? 'deploy:write'
+        : 'deploy:read';
+const resource_of = (base) => `${base}/mcp`;
+/** RFC 9728 Protected Resource Metadata. */
+const protected_resource_metadata = (base) => ({
+    resource: resource_of(base),
+    authorization_servers: [AUTH_ISSUER],
+    scopes_supported: ALL_SCOPES,
+    bearer_methods_supported: ['header'],
+    resource_name: 'Faable',
+    resource_documentation: 'https://faable.com/mcp'
+});
+const prm_url = (base) => `${base}/.well-known/oauth-protected-resource/mcp`;
+/** The `WWW-Authenticate` of a 401/403 (RFC 6750 §3, MCP authorization). */
+const www_authenticate = (base, extra = {}) => [
+    'Bearer realm="faable"',
+    `resource_metadata="${prm_url(base)}"`,
+    `scope="${(extra.scope ?? DEFAULT_SCOPES).join(' ')}"`,
+    ...(extra.error ? [`error="${extra.error}"`] : [])
+].join(', ');
+const looks_like_jwt = (token) => /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
+let jwks_cache = null;
+const JWKS_TTL_MS = 10 * 60 * 1000;
+let http = (input, init) => fetch(input, init);
+const jwk_for = async (kid) => {
+    const pick = (keys) => keys.find(k => !kid || k.kid === kid);
+    if (jwks_cache && Date.now() - jwks_cache.at < JWKS_TTL_MS) {
+        const hit = pick(jwks_cache.keys);
+        if (hit)
+            return hit;
+    }
+    // A kid we do not know yet may be a rotation: fetch once more.
+    const res = await http(`${AUTH_ISSUER}/.well-known/jwks.json`);
+    if (!res.ok)
+        throw new Error(`jwks: HTTP ${res.status}`);
+    const body = (await res.json());
+    jwks_cache = { keys: body.keys ?? [], at: Date.now() };
+    return pick(jwks_cache.keys);
+};
+const b64json = (part) => JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+class InvalidToken extends Error {
+}
+/** The claims of a valid token for this resource, or InvalidToken. */
+const verify_access_token = async (token, resource) => {
+    const [h, p, s] = token.split('.');
+    let header;
+    let claims;
+    try {
+        header = b64json(h);
+        claims = b64json(p);
+    }
+    catch {
+        throw new InvalidToken('malformed token');
+    }
+    if (header.alg !== 'RS256')
+        throw new InvalidToken('unexpected algorithm');
+    if (claims.iss !== AUTH_ISSUER)
+        throw new InvalidToken('unexpected issuer');
+    const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    // RFC 8707 / MCP: a token for another resource is not ours to accept.
+    if (!aud.includes(resource))
+        throw new InvalidToken('token is for another resource');
+    if (!claims.exp || claims.exp * 1000 < Date.now())
+        throw new InvalidToken('token expired');
+    const jwk = await jwk_for(header.kid);
+    if (!jwk)
+        throw new InvalidToken('unknown signing key');
+    const ok = verify('RSA-SHA256', Buffer.from(`${h}.${p}`), createPublicKey({ key: jwk, format: 'jwk' }), Buffer.from(s, 'base64url'));
+    if (!ok)
+        throw new InvalidToken('bad signature');
+    if (!claims.sub)
+        throw new InvalidToken('token has no subject');
+    return claims;
+};
+const permissions_of = (claims) => String(claims.permissions ?? '')
+    .split(' ')
+    .filter((p) => ALL_SCOPES.includes(p));
+// ── Trading it for our own (RFC 8693) ─────────────────────────────────────
+const exchange_cache = new Map();
+// Shorter than the delegated token's own life, so a cached one never expires
+// mid-call, and short enough that a disconnected app stops within a minute.
+const EXCHANGE_CACHE_MS = 60 * 1000;
+class ExchangeRefused extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+const delegated_token_for = async (subject) => {
+    const key = createHash('sha256').update(subject).digest('base64url');
+    const hit = exchange_cache.get(key);
+    if (hit && hit.until > Date.now())
+        return hit.token;
+    const res = await http(`${AUTH_ISSUER}/oauth/token`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+            'x-faable-client': 'faable-mcp'
+        },
+        body: new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+            client_id: process.env.FAABLE_MCP_CLIENT_ID ?? '',
+            client_secret: process.env.FAABLE_MCP_CLIENT_SECRET ?? '',
+            subject_token: subject,
+            subject_token_type: 'urn:ietf:params:oauth:token-type:access_token'
+        }).toString()
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.access_token) {
+        throw new ExchangeRefused(body.error_description ?? `token exchange: HTTP ${res.status}`, res.status);
+    }
+    exchange_cache.set(key, {
+        token: body.access_token,
+        until: Date.now() + EXCHANGE_CACHE_MS
+    });
+    // Bounded: one entry per live connection, swept as they expire.
+    if (exchange_cache.size > 5000) {
+        for (const [k, v] of exchange_cache)
+            if (v.until <= Date.now())
+                exchange_cache.delete(k);
+    }
+    return body.access_token;
+};
+
+export { ALL_SCOPES, AUTH_ISSUER, DEFAULT_SCOPES, ExchangeRefused, InvalidToken, delegated_token_for, looks_like_jwt, oauth_enabled, permission_of, permissions_of, prm_url, protected_resource_metadata, resource_of, verify_access_token, www_authenticate };

package/dist/mcp/server.js

@@ -94,7 +94,8 @@ const build_log_text = (b) => {
     ];
     return head.concat(b.content).join('\n');
 };
-const tools_for = (opts) => TOOLS.filter(t => opts.readonly ? t.annotations.readOnlyHint : !t.write || opts.writes);
+const tools_for = (opts) => TOOLS.filter(t => (opts.readonly ? t.annotations.readOnlyHint : !t.write || opts.writes) &&
+    (!opts.allow || opts.allow(t)));
 const create_server = (opts = {}) => {
     const server = new McpServer({ name: 'faable', title: 'Faable', version }, { instructions: INSTRUCTIONS });
     for (const tool of tools_for(opts)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "4.5.4",
+  "version": "4.6.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",