@ni-c/mcp-hub 0.9.2 → 0.11.0

package/dist/auth/store.js

@@ -1,6 +1,31 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+export const DEFAULT_CLIENT_LIMITS = {
+    maxClients: 500,
+    pendingTtlSeconds: 24 * 3600,
+    inactiveSeconds: 90 * 86_400
+};
+/**
+ * Activity is only written to disk once an hour. The windows it feeds are a day
+ * and three months, so recording it per request would buy nothing and cost a
+ * lock plus a full rewrite of state.json on every authorization.
+ */
+const ACTIVITY_GRANULARITY_S = 3600;
+/**
+ * A revocation marker only has to outlive the longest-lived token it could
+ * still reject. Refresh tokens last 30 days, so anything older is answering a
+ * question nobody can ask any more — and without this the map is the one
+ * structure that only ever grows.
+ */
+const REVOCATION_MARKER_TTL_MS = 31 * 24 * 3600_000;
+/**
+ * Every artifact expires and every write prunes, so this cap is not the primary
+ * bound — it is the backstop for the one case pruning cannot help with: tokens
+ * minted faster than they age out. Eviction is oldest-first, which for tokens
+ * costs a client one refresh rather than its session.
+ */
+const MAX_OIDC_ARTIFACTS_PER_MODEL = 5_000;
 /**
  * Registration is open (anyone can POST /register), so unconfirmed clients
  * would otherwise accumulate on disk without bound and every registration
@@ -8,6 +33,29 @@ import path from 'node:path';
  * approved; approved ones are legitimate and never evicted.
  */
 export const MAX_UNAPPROVED_CLIENTS = 100;
+/**
+ * The same limits the hub runs with, so `mcp-hub-admin clients prune` removes
+ * exactly what the hub would. The documented invocation is `docker exec` into
+ * the hub container, which shares its environment.
+ */
+export function clientLimitsFromEnv(env = process.env) {
+    const read = (name, fallback) => {
+        const raw = env[name];
+        if (raw === undefined)
+            return fallback;
+        const value = Number(raw);
+        if (!Number.isSafeInteger(value) || value < 1) {
+            console.warn(`mcp-hub: ignoring ${name}=${raw}; it must be a positive integer`);
+            return fallback;
+        }
+        return value;
+    };
+    return {
+        maxClients: read('DCR_MAX_CLIENTS', 500),
+        pendingTtlSeconds: read('DCR_PENDING_TTL_HOURS', 24) * 3600,
+        inactiveSeconds: read('DCR_INACTIVE_DAYS', 90) * 86_400
+    };
+}
 const LOCK_WAIT_MS = 10_000;
 const STALE_LOCK_MS = 30_000;
 const LOCK_POLL_MS = 10;
@@ -28,18 +76,23 @@ const lockSleep = new Int32Array(new SharedArrayBuffer(4));
  * read-modify-write.
  */
 export class AuthStore {
+    limits;
     privateKey;
     publicKey;
     state;
     statePath;
     lockPath;
+    upstreamKeyPath;
+    cachedUpstreamKey;
     /** Identity of the file contents this.state was loaded from; see fileSignature(). */
     signature;
     tmpCounter = 0;
-    constructor(dataDir) {
+    constructor(dataDir, limits = DEFAULT_CLIENT_LIMITS) {
+        this.limits = limits;
         fs.mkdirSync(dataDir, { recursive: true });
         this.statePath = path.join(dataDir, 'state.json');
         this.lockPath = path.join(dataDir, '.auth-state.lock');
+        this.upstreamKeyPath = path.join(dataDir, 'upstream-key.pem');
         this.acquireLock();
         try {
             const keyPath = path.join(dataDir, 'jwt-key.pem');
@@ -57,7 +110,11 @@ export class AuthStore {
                 approvals: {},
                 consumedRefreshTokens: {},
                 revokedBefore: {},
-                apiTokens: {}
+                apiTokens: {},
+                clientLifecycle: {},
+                upstreamCredentials: {},
+                upstreamLogins: {},
+                oidcArtifacts: {}
             };
             if (restored)
                 this.signature = this.fileSignature();
@@ -248,7 +305,12 @@ export class AuthStore {
             approvals: state.approvals ?? {},
             consumedRefreshTokens: state.consumedRefreshTokens ?? {},
             revokedBefore: state.revokedBefore ?? {},
-            apiTokens: state.apiTokens ?? {}
+            apiTokens: state.apiTokens ?? {},
+            clientLifecycle: state.clientLifecycle ?? {},
+            upstreamCredentials: state.upstreamCredentials ?? {},
+            upstreamLogins: state.upstreamLogins ?? {},
+            oidcArtifacts: state.oidcArtifacts ?? {},
+            ...(typeof state.externalUrl === 'string' ? { externalUrl: state.externalUrl } : {})
         };
     }
     /**
@@ -306,6 +368,135 @@ export class AuthStore {
             if (record.expiresAt < now)
                 delete this.state.apiTokens[id];
         }
+        // A marker that can no longer reject anything is just a row that never
+        // goes away; this is otherwise the one map with no upper bound.
+        const markerCutoff = Date.now() - REVOCATION_MARKER_TTL_MS;
+        for (const [clientId, revokedAt] of Object.entries(this.state.revokedBefore)) {
+            if (revokedAt < markerCutoff)
+                delete this.state.revokedBefore[clientId];
+        }
+        // Bookkeeping for a client that is gone serves nobody.
+        for (const clientId of Object.keys(this.state.clientLifecycle)) {
+            if (!this.state.clients[clientId])
+                delete this.state.clientLifecycle[clientId];
+        }
+        // A login nobody finished. Note this sweeps only the in-flight record —
+        // UpstreamCredentials deliberately has no `expiresAt`, because an expired
+        // access token still has a usable refresh token behind it.
+        for (const [state, login] of Object.entries(this.state.upstreamLogins)) {
+            if (login.expiresAt < now)
+                delete this.state.upstreamLogins[state];
+        }
+        for (const [model, records] of Object.entries(this.state.oidcArtifacts)) {
+            for (const [id, record] of Object.entries(records)) {
+                if (record.expiresAt !== 0 && record.expiresAt < now)
+                    delete records[id];
+            }
+            const ids = Object.keys(records);
+            if (ids.length > MAX_OIDC_ARTIFACTS_PER_MODEL) {
+                const byAge = ids.sort((a, b) => (records[a].expiresAt || Infinity) - (records[b].expiresAt || Infinity));
+                for (const id of byAge.slice(0, ids.length - MAX_OIDC_ARTIFACTS_PER_MODEL))
+                    delete records[id];
+            }
+            // An empty model map is a row that never goes away.
+            if (Object.keys(records).length === 0)
+                delete this.state.oidcArtifacts[model];
+        }
+    }
+    // --- Upstream OAuth ------------------------------------------------------
+    /** The issuer the hub is running under, recorded so the admin CLI can build a
+     *  redirect URI without EXTERNAL_URL in its own environment. */
+    rememberExternalUrl(externalUrl) {
+        this.reloadIfChanged();
+        if (this.state.externalUrl === externalUrl)
+            return;
+        this.mutate(() => {
+            this.state.externalUrl = externalUrl;
+        });
+    }
+    getExternalUrl() {
+        this.reloadIfChanged();
+        return this.state.externalUrl;
+    }
+    /**
+     * What the hub holds for one upstream, or undefined when there is nothing —
+     * including when the configuration moved out from under it, which is what the
+     * fingerprint detects. Stale credentials are not returned and not deleted:
+     * deleting on a read would race the admin CLI, and the next successful login
+     * overwrites them anyway.
+     */
+    getUpstreamCredentials(serverName, fingerprint) {
+        this.reloadIfChanged();
+        const record = this.state.upstreamCredentials[serverName];
+        if (!record || record.fingerprint !== fingerprint)
+            return undefined;
+        return structuredClone(record);
+    }
+    /** Every stored upstream, whatever its fingerprint — for `upstream list`. */
+    listUpstreamCredentials() {
+        this.reloadIfChanged();
+        return structuredClone(this.state.upstreamCredentials);
+    }
+    /**
+     * Read-modify-write of one upstream's record. The callback runs while the
+     * cross-process lock is held, so it must not do I/O — it gets the current
+     * record (or undefined) and returns the one to store.
+     */
+    updateUpstreamCredentials(serverName, update) {
+        this.mutate(() => {
+            this.state.upstreamCredentials[serverName] = update(this.state.upstreamCredentials[serverName]);
+        });
+    }
+    forgetUpstreamCredentials(serverName) {
+        return this.mutate(() => {
+            if (!this.state.upstreamCredentials[serverName])
+                return false;
+            delete this.state.upstreamCredentials[serverName];
+            return true;
+        });
+    }
+    saveUpstreamLogin(state, login) {
+        this.mutate(() => {
+            this.state.upstreamLogins[state] = login;
+        });
+    }
+    listUpstreamLogins() {
+        this.reloadIfChanged();
+        return structuredClone(this.state.upstreamLogins);
+    }
+    /** Single-use: the record is removed as it is read, so a replayed callback
+     *  finds nothing even if the signed state is still within its lifetime. */
+    takeUpstreamLogin(state) {
+        return this.mutate(() => {
+            const login = this.state.upstreamLogins[state];
+            if (!login)
+                return undefined;
+            delete this.state.upstreamLogins[state];
+            return login.expiresAt < Math.floor(Date.now() / 1000) ? undefined : login;
+        });
+    }
+    /**
+     * The key the hub signs outbound `private_key_jwt` assertions with.
+     *
+     * Deliberately *not* `jwt-key.pem`: that one signs access tokens the hub
+     * issues to its own clients, and a key that both mints local credentials and
+     * proves identity to a third party is one key doing two jobs. Created on
+     * first use, because most deployments never need it.
+     */
+    get upstreamPrivateKey() {
+        if (!this.cachedUpstreamKey) {
+            if (!fs.existsSync(this.upstreamKeyPath)) {
+                const { privateKey } = crypto.generateKeyPairSync('ed25519');
+                fs.writeFileSync(this.upstreamKeyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+            }
+            this.cachedUpstreamKey = crypto.createPrivateKey(fs.readFileSync(this.upstreamKeyPath, 'utf8'));
+        }
+        return this.cachedUpstreamKey;
+    }
+    /** The lifecycle limits this store was built with, for callers that need to
+     *  report them. */
+    get clientLimits() {
+        return this.limits;
     }
     get cookieSecret() {
         this.reloadIfChanged();
@@ -325,6 +516,205 @@ export class AuthStore {
             this.pruneUnapprovedClients();
         });
     }
+    /**
+     * Records a newly registered client, or answers false when the hub is full.
+     *
+     * Full means the ceiling is reached and every registration under it has been
+     * approved. Making room by dropping one of those would take a connector
+     * somebody is using offline — and an attacker who can register at will would
+     * be able to aim that at a specific victim. Refusing the newcomer is the
+     * failure the operator can see and fix.
+     */
+    addClient(client, registrationToken, options = {}) {
+        return this.mutate(() => {
+            this.pruneUnderLock();
+            // An operator-created client is not subject to the ceiling either: it was
+            // asked for deliberately, and refusing it would be refusing the person
+            // who administers the hub.
+            if (!options.operatorManaged && !this.makeRoomForOneClient())
+                return false;
+            this.state.clients[client.client_id] = client;
+            this.state.clientLifecycle[client.client_id] = {
+                ...(registrationToken ? { registrationTokenHash: AuthStore.hash(registrationToken) } : {}),
+                ...(options.operatorManaged ? { operatorManaged: true } : {}),
+                lastActiveAt: Math.floor(Date.now() / 1000)
+            };
+            this.pruneUnapprovedClients();
+            return true;
+        });
+    }
+    /** True for a client the operator created by hand. */
+    isOperatorManaged(clientId) {
+        this.reloadIfChanged();
+        return this.state.clientLifecycle[clientId]?.operatorManaged === true;
+    }
+    /** Evicts never-approved registrations until one more fits, and reports
+     *  whether it managed to. */
+    makeRoomForOneClient() {
+        const fits = () => Object.keys(this.state.clients).length < this.limits.maxClients;
+        if (fits())
+            return true;
+        const evictable = Object.values(this.state.clients)
+            .filter(candidate => !this.state.approvals[candidate.client_id] && !this.isOperatorManagedUnderLock(candidate.client_id))
+            .sort((a, b) => (a.client_id_issued_at ?? 0) - (b.client_id_issued_at ?? 0));
+        for (const candidate of evictable) {
+            this.forgetClient(candidate.client_id);
+            if (fits())
+                return true;
+        }
+        return fits();
+    }
+    /** RFC 7592 update. Changing the redirect URIs withdraws the approval: it was
+     *  given for a specific destination, and the client does not get to move that
+     *  destination afterwards without being asked again. */
+    updateClient(client, options = {}) {
+        this.mutate(() => {
+            if (!this.state.clients[client.client_id])
+                return;
+            this.state.clients[client.client_id] = client;
+            if (options.resetApproval)
+                delete this.state.approvals[client.client_id];
+        });
+    }
+    /** Removes a registration outright — the client, its approval, its refresh
+     *  tokens and, so live access tokens stop working now rather than in fifteen
+     *  minutes, a revocation marker. */
+    deleteClient(clientId) {
+        return this.mutate(() => {
+            if (!this.state.clients[clientId] && !this.state.approvals[clientId])
+                return false;
+            this.forgetClient(clientId);
+            delete this.state.approvals[clientId];
+            for (const [hash, record] of Object.entries(this.state.refreshTokens)) {
+                if (record.clientId === clientId)
+                    delete this.state.refreshTokens[hash];
+            }
+            this.state.revokedBefore[clientId] = Date.now();
+            return true;
+        });
+    }
+    /** The same question as isOperatorManaged(), for a caller that already holds
+     *  the lock and must not re-read the file underneath itself. */
+    isOperatorManagedUnderLock(clientId) {
+        return this.state.clientLifecycle[clientId]?.operatorManaged === true;
+    }
+    forgetClient(clientId) {
+        delete this.state.clients[clientId];
+        delete this.state.clientLifecycle[clientId];
+    }
+    /** Notes that a client was used. Cheap to call on every request: it only
+     *  reaches the disk once an hour, and never fails the caller. */
+    touchClient(clientId) {
+        try {
+            this.reloadIfChanged();
+            const entry = this.state.clientLifecycle[clientId];
+            if (!entry)
+                return; // a metadata-document client has no registration to age
+            const now = Math.floor(Date.now() / 1000);
+            if (now - entry.lastActiveAt < ACTIVITY_GRANULARITY_S)
+                return;
+            this.mutate(() => {
+                const current = this.state.clientLifecycle[clientId];
+                if (current)
+                    current.lastActiveAt = now;
+            });
+        }
+        catch (error) {
+            // Bookkeeping must never be the reason an authorization fails.
+            console.warn(`mcp-hub: could not record activity for client ${clientId}: ${error.message}`);
+        }
+    }
+    /** Timing-safe check of an RFC 7592 registration access token. */
+    /**
+     * Attaches the hash of a registration access token to an existing client.
+     *
+     * The authorization server mints the token and only ever reveals it in the
+     * registration response, so the hash has to be recorded from there rather
+     * than at the moment the client record is written.
+     */
+    rememberRegistrationToken(clientId, token) {
+        this.mutate(() => {
+            const entry = this.state.clientLifecycle[clientId];
+            if (entry)
+                entry.registrationTokenHash = AuthStore.hash(token);
+        });
+    }
+    verifyRegistrationToken(clientId, token) {
+        this.reloadIfChanged();
+        const expected = this.state.clientLifecycle[clientId]?.registrationTokenHash;
+        if (!expected)
+            return false;
+        const given = AuthStore.hash(token);
+        return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
+    }
+    /** What a prune would remove right now, without removing it. */
+    planClientPrune() {
+        this.reloadIfChanged();
+        const { pending, inactive } = this.classifyClients();
+        return { pending, inactive };
+    }
+    /**
+     * Drops registrations that were never confirmed and ones nobody has used in
+     * a long time. Only touches disk when there is something to do.
+     *
+     * Metadata-document clients are unaffected: they are never stored here, so
+     * the approval that is their only trace is left alone.
+     */
+    pruneClients() {
+        this.reloadIfChanged();
+        const preview = this.classifyClients();
+        if (preview.pending.length === 0 && preview.inactive.length === 0 && preview.undated.length === 0) {
+            return { pending: [], inactive: [] };
+        }
+        return this.mutate(() => this.pruneUnderLock());
+    }
+    classifyClients() {
+        const now = Math.floor(Date.now() / 1000);
+        const pending = [];
+        const inactive = [];
+        const undated = [];
+        for (const clientId of Object.keys(this.state.clients)) {
+            const lifecycle = this.state.clientLifecycle[clientId];
+            if (!lifecycle) {
+                undated.push(clientId);
+                continue;
+            }
+            if (lifecycle.operatorManaged)
+                continue;
+            const idle = now - lifecycle.lastActiveAt;
+            if (!this.state.approvals[clientId]) {
+                if (idle >= this.limits.pendingTtlSeconds)
+                    pending.push(clientId);
+            }
+            else if (idle >= this.limits.inactiveSeconds) {
+                inactive.push(clientId);
+            }
+        }
+        return { pending, inactive, undated };
+    }
+    /** The sweep itself. The only implementation, so a registration and the
+     *  periodic pass cannot drift apart in what they clean up. */
+    pruneUnderLock() {
+        const { pending, inactive, undated } = this.classifyClients();
+        // A state file written before activity was tracked has no clock for its
+        // clients. Starting that clock now, rather than reading it as "idle since
+        // registration", is what stops an upgrade from deleting every connector
+        // that happens to predate the inactivity window.
+        const now = Math.floor(Date.now() / 1000);
+        for (const clientId of undated)
+            this.state.clientLifecycle[clientId] = { lastActiveAt: now };
+        for (const clientId of pending)
+            this.forgetClient(clientId);
+        for (const clientId of inactive) {
+            this.forgetClient(clientId);
+            delete this.state.approvals[clientId];
+            for (const [hash, record] of Object.entries(this.state.refreshTokens)) {
+                if (record.clientId === clientId)
+                    delete this.state.refreshTokens[hash];
+            }
+        }
+        return { pending, inactive };
+    }
     /**
      * Evict the oldest never-approved clients once too many pile up. A client
      * with an approval entry is one the operator confirmed and is kept; the just
@@ -332,10 +722,10 @@ export class AuthStore {
      */
     pruneUnapprovedClients() {
         const unapproved = Object.values(this.state.clients)
-            .filter(c => !this.state.approvals[c.client_id])
+            .filter(c => !this.state.approvals[c.client_id] && !this.isOperatorManagedUnderLock(c.client_id))
             .sort((a, b) => (a.client_id_issued_at ?? 0) - (b.client_id_issued_at ?? 0));
         for (let i = 0; i < unapproved.length - MAX_UNAPPROVED_CLIENTS; i++) {
-            delete this.state.clients[unapproved[i].client_id];
+            this.forgetClient(unapproved[i].client_id);
         }
     }
     getApproval(clientId) {
@@ -459,5 +849,126 @@ export class AuthStore {
             return true;
         });
     }
+    // --- oidc-provider artifacts ---------------------------------------------
+    //
+    // The backing store for the ten adapter models. Deliberately dumb: the
+    // library owns the payload shapes, so this layer only adds the two things it
+    // cannot do itself — the cross-process lock every other writer here obeys,
+    // and the revokedBefore cutoff below.
+    /**
+     * Artifacts are keyed by the HASH of their id, never by the id itself.
+     *
+     * With opaque access tokens the id IS the bearer token, and a refresh token
+     * or a registration access token is no different — storing them verbatim
+     * would turn read access to state.json into working credentials. The file was
+     * already sensitive (it holds the cookie secret), but it never used to hold
+     * anything an attacker could present as-is, and it should not start now.
+     *
+     * Lookups all go through here, and the two scans (`findByUid`,
+     * `revokeByGrantId`) match on payload fields rather than on the key, so
+     * nothing needs the plaintext back.
+     */
+    static artifactKey(id) {
+        return AuthStore.hash(id);
+    }
+    /**
+     * Models whose id is a bearer credential someone presents back.
+     *
+     * Hashing the key alone would not be enough: the payload carries `jti`, and
+     * for an opaque token the jti IS the token. These are stored without it and
+     * get it back from the lookup id on the way out, which `find` always has.
+     * The others (Session, Interaction, Grant) are referenced by ids that are not
+     * credentials, and their jti has to survive a `findByUid` that never sees one.
+     */
+    static CREDENTIAL_MODELS = new Set([
+        'AccessToken',
+        'RefreshToken',
+        'AuthorizationCode',
+        'RegistrationAccessToken',
+        'ClientCredentials',
+        'InitialAccessToken',
+        'DeviceCode',
+        'BackchannelAuthenticationRequest'
+    ]);
+    oidcUpsert(model, id, payload, expiresInSeconds) {
+        this.mutate(() => {
+            const records = (this.state.oidcArtifacts[model] ??= {});
+            const key = AuthStore.artifactKey(id);
+            const stored = AuthStore.CREDENTIAL_MODELS.has(model) ? { ...payload, jti: undefined } : payload;
+            if (AuthStore.CREDENTIAL_MODELS.has(model))
+                delete stored.jti;
+            records[key] = {
+                payload: stored,
+                expiresAt: expiresInSeconds ? Math.floor(Date.now() / 1000) + expiresInSeconds : 0,
+                ...(records[key]?.consumedAt !== undefined ? { consumedAt: records[key].consumedAt } : {})
+            };
+        });
+    }
+    /**
+     * Undefined for unknown, expired *and revoked* artifacts — the library treats
+     * every falsy return as "not found", so this one comparison is the whole of
+     * `mcp-hub-admin clients revoke`. It is why access tokens are opaque: a JWT
+     * is never stored, so it could not be reached here at all.
+     */
+    oidcFind(model, id) {
+        this.reloadIfChanged();
+        const record = this.state.oidcArtifacts[model]?.[AuthStore.artifactKey(id)];
+        if (!record)
+            return undefined;
+        if (record.expiresAt !== 0 && record.expiresAt < Math.floor(Date.now() / 1000))
+            return undefined;
+        const clientId = record.payload.clientId;
+        const issuedAt = record.payload.iat;
+        if (typeof clientId === 'string' && typeof issuedAt === 'number') {
+            const cutoff = this.state.revokedBefore[clientId];
+            if (cutoff !== undefined && issuedAt * 1000 < cutoff)
+                return undefined;
+        }
+        const payload = AuthStore.CREDENTIAL_MODELS.has(model) ? { ...record.payload, jti: id } : record.payload;
+        return record.consumedAt === undefined ? payload : { ...payload, consumed: record.consumedAt };
+    }
+    /** Sessions are looked up by `uid` as well as by id. */
+    oidcFindBy(model, field, value) {
+        this.reloadIfChanged();
+        for (const record of Object.values(this.state.oidcArtifacts[model] ?? {})) {
+            if (record.payload[field] !== value)
+                continue;
+            if (record.expiresAt !== 0 && record.expiresAt < Math.floor(Date.now() / 1000))
+                return undefined;
+            return record.payload;
+        }
+        return undefined;
+    }
+    oidcConsume(model, id) {
+        this.mutate(() => {
+            const record = this.state.oidcArtifacts[model]?.[AuthStore.artifactKey(id)];
+            if (record)
+                record.consumedAt = Math.floor(Date.now() / 1000);
+        });
+    }
+    oidcDestroy(model, id) {
+        this.mutate(() => {
+            delete this.state.oidcArtifacts[model]?.[AuthStore.artifactKey(id)];
+        });
+    }
+    /**
+     * Scanned rather than indexed. A second index would be a third thing to keep
+     * consistent across a crash between two writes, and these maps hold hundreds
+     * of rows, not millions.
+     */
+    oidcRevokeByGrantId(grantId) {
+        return this.mutate(() => {
+            let revoked = 0;
+            for (const records of Object.values(this.state.oidcArtifacts)) {
+                for (const [id, record] of Object.entries(records)) {
+                    if (record.payload.grantId === grantId) {
+                        delete records[id];
+                        revoked++;
+                    }
+                }
+            }
+            return revoked;
+        });
+    }
 }
 //# sourceMappingURL=store.js.map