@typeship-ax/mcp 0.8.0 → 0.9.1

package/dist/oauth-request.js

@@ -0,0 +1,119 @@
+export class OAuthResponseError extends Error {
+    code;
+    constructor(code) {
+        const messages = {
+            request_failed: "OAuth request failed. Check the configured provider endpoint.",
+            timed_out: "OAuth request timed out. Run login again to retry.",
+            cancelled: "OAuth request was cancelled.",
+            response_too_large: "OAuth provider response exceeded 1 MiB.",
+            invalid_response: "OAuth provider returned an invalid JSON response.",
+        };
+        super(messages[code]);
+        this.code = code;
+        this.name = "OAuthResponseError";
+    }
+}
+/** Error bodies and transport causes may contain credentials and are discarded. */
+export function oauthJsonRequest(url, init = {}, timeoutMs = 30_000) {
+    return boundedRequest(url, init, timeoutMs, "json");
+}
+/** Device polling needs four protocol errors. Return only their exact names,
+ * never descriptions, error URIs, arbitrary error codes or other body fields. */
+export function oauthDeviceRequest(url, init = {}, timeoutMs = 30_000) {
+    return boundedRequest(url, init, timeoutMs, "device");
+}
+/** Revocation may return an empty success body. Do not wait for or parse it. */
+export function oauthStatusRequest(url, init = {}, timeoutMs = 30_000) {
+    return boundedRequest(url, init, timeoutMs, "status");
+}
+/** Bound the entire exchange, including decoded response bytes. */
+async function boundedRequest(url, init, timeoutMs, mode) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000)
+        throw new OAuthResponseError("request_failed");
+    const controller = new AbortController();
+    let reader;
+    let timer;
+    let interrupted;
+    let rejectDeadline;
+    const deadline = new Promise((_, reject) => { rejectDeadline = reject; });
+    const stop = (code) => { interrupted ??= code; rejectDeadline(new OAuthResponseError(interrupted)); controller.abort(); };
+    const cancel = () => stop("cancelled");
+    init.signal?.addEventListener("abort", cancel, { once: true });
+    timer = setTimeout(() => stop("timed_out"), timeoutMs);
+    try {
+        if (init.signal?.aborted)
+            throw new OAuthResponseError("cancelled");
+        const request = { ...init, redirect: "error", credentials: "omit", cache: "no-store", signal: controller.signal };
+        const response = await Promise.race([
+            fetch(url, request).then((value) => {
+                // Also dispose a late response from a transport that ignored abort.
+                if (controller.signal.aborted)
+                    void value.body?.cancel().catch(() => { });
+                return value;
+            }), deadline,
+        ]);
+        if (response.redirected) {
+            void response.body?.cancel().catch(() => { });
+            throw new OAuthResponseError("request_failed");
+        }
+        if (mode === "status" || response.status !== 200 && !(mode === "device" && response.status === 400)) {
+            void response.body?.cancel().catch(() => { });
+            return { status: response.status };
+        }
+        if (!response.body)
+            throw new OAuthResponseError("invalid_response");
+        reader = response.body.getReader();
+        let size = 0, text = "";
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        while (true) {
+            const chunk = await Promise.race([reader.read(), deadline]);
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 1_048_576)
+                throw new OAuthResponseError("response_too_large");
+            try {
+                text += decoder.decode(chunk.value, { stream: true });
+            }
+            catch {
+                throw new OAuthResponseError("invalid_response");
+            }
+        }
+        try {
+            text += decoder.decode();
+        }
+        catch {
+            throw new OAuthResponseError("invalid_response");
+        }
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new OAuthResponseError("invalid_response");
+        }
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            throw new OAuthResponseError("invalid_response");
+        if (response.status !== 200) {
+            const error = data.error;
+            return { status: response.status, ...(["authorization_pending", "slow_down", "access_denied", "expired_token"].includes(String(error)) && typeof error === "string" ? { error: error } : {}) };
+        }
+        return { status: response.status, data: data };
+    }
+    catch (error) {
+        if (interrupted)
+            throw new OAuthResponseError(interrupted);
+        if (error instanceof OAuthResponseError)
+            throw error;
+        throw new OAuthResponseError("request_failed");
+    }
+    finally {
+        clearTimeout(timer);
+        init.signal?.removeEventListener("abort", cancel);
+        controller.abort();
+        if (reader) {
+            void reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
+}

package/dist/oauth-session.d.ts

@@ -0,0 +1,106 @@
+import { type IdentityConfiguration, type VerifiedIdentity } from "./api-identity.js";
+export interface StoredOAuthSession {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenUrl?: string;
+    issuer?: string;
+    clientId?: string;
+    revocationUrl?: string;
+    apiBaseUrl?: string;
+    configuredClientId?: string | null;
+    scopes?: string[];
+    /** New login identity, independent of rotating tokens. */
+    sessionId: string;
+    binding: string;
+    /** Persisted before exchange: an interrupted exchange must not replay a rotating token. */
+    refreshPending?: boolean;
+}
+export interface CredentialDestination {
+    apiBaseUrl: string;
+    environment?: string;
+    profile?: string;
+}
+export declare function assertCredentialDestination(credentials: StoredCredentials, destination: CredentialDestination): void;
+export interface StoredCredentials {
+    destination?: CredentialDestination;
+    named?: Record<string, string | {
+        username: string;
+        password: string;
+    }>;
+    scalars?: Record<string, string>;
+    basic?: {
+        username: string;
+        password: string;
+    };
+    oauth?: StoredOAuthSession;
+    identity?: VerifiedIdentity & {
+        binding: string;
+    };
+    minted?: {
+        via: "browser";
+        key_name: string;
+        org_id?: string;
+        revocationUrl?: string;
+    };
+}
+export interface SessionConfiguration extends CredentialDestination {
+    identity?: IdentityConfiguration;
+    verifyIdentity?: (accessToken: string) => Promise<VerifiedIdentity>;
+    clientId?: string | null;
+    issuer?: string | null;
+    tokenUrl?: string | null;
+    discoveryUrl?: string | null;
+    authorizationUrl?: string | null;
+    scopes?: string[];
+    audience?: string;
+    resource?: string;
+    organizationParameter?: "organization" | "organization_id";
+}
+/** Bind minimal identity evidence to this credential set and its configured read. */
+export declare function credentialIdentityBinding(credentials: StoredCredentials, identity: IdentityConfiguration): string;
+export declare function assertStoredIdentity(credentials: StoredCredentials, identity?: IdentityConfiguration): void;
+/** Bind the login to effective nonsecret settings. Scope ordering is irrelevant. */
+export declare function sessionBinding(config: SessionConfiguration): string;
+interface LockedCredentials {
+    read(): StoredCredentials | null;
+    write(credentials: StoredCredentials | null): void;
+}
+export interface CredentialStore {
+    read(): StoredCredentials | null;
+    withLock<T>(work: (store: LockedCredentials) => Promise<T>): Promise<T>;
+}
+export declare class CredentialStorageError extends Error {
+}
+export interface CredentialCodec {
+    readonly name: string;
+    prepare(): void;
+    encode(plaintext: string): string;
+    decode(encoded: string): string;
+}
+/** Private file adapter. All writers (login, refresh and logout) use the same
+ * cross-process lock. Credential storage can be replaced independently of OAuth. */
+export declare class FileCredentialStore implements CredentialStore {
+    readonly path: string;
+    private readonly lockTimeoutMs;
+    private readonly codec?;
+    constructor(path: string, lockTimeoutMs?: number, codec?: CredentialCodec | undefined);
+    get backend(): string;
+    /** Check storage access before starting an interactive login. */
+    prepare(): Promise<void>;
+    read(): StoredCredentials | null;
+    private write;
+    withLock<T>(work: (store: LockedCredentials) => Promise<T>): Promise<T>;
+    private recoverDeadOwner;
+    update(change: (current: StoredCredentials) => StoredCredentials): Promise<void>;
+    /** Explicit local-only logout can remove an unreadable encrypted session. */
+    clear(): Promise<boolean>;
+    /** Remove under the refresh lock, then revoke the latest token outside it. */
+    take(): Promise<StoredCredentials | null>;
+}
+/** Re-read on every request attempt; only one process may rotate the token.
+ * A failed or interrupted exchange requires login, since the server may have
+ * consumed its refresh token even when no response reached this process. */
+export declare function oauthSessionToken(store: CredentialStore, config: SessionConfiguration, sessionId: string, tokenParams?: Record<string, string>): Promise<string>;
+export {};
+//# sourceMappingURL=oauth-session.d.ts.map

package/dist/oauth-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-session.d.ts","sourceRoot":"","sources":["../src/oauth-session.ts"],"names":[],"mappings":"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"}

package/dist/oauth-session.js

@@ -0,0 +1,244 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { assertApiIdentity } from "./api-identity.js";
+import { oauthJsonRequest } from "./oauth-request.js";
+export function assertCredentialDestination(credentials, destination) {
+    const saved = credentials.destination;
+    if (!saved)
+        throw new Error("Saved credentials have no API and profile binding. Log in again before using them.");
+    if (new URL(saved.apiBaseUrl).href !== new URL(destination.apiBaseUrl).href)
+        throw new Error("The API destination changed. Log in again before using saved credentials.");
+    if ((saved.environment ?? null) !== (destination.environment ?? null) || (saved.profile ?? null) !== (destination.profile ?? null))
+        throw new Error("The credential environment or profile changed. Log in again before using saved credentials.");
+}
+/** Bind minimal identity evidence to this credential set and its configured read. */
+export function credentialIdentityBinding(credentials, identity) {
+    return createHash("sha256").update(JSON.stringify({
+        destination: credentials.destination, scalars: credentials.scalars, named: credentials.named, basic: credentials.basic,
+        oauth: credentials.oauth ? { sessionId: credentials.oauth.sessionId, binding: credentials.oauth.binding } : undefined,
+        operation: identity.operation, fields: Object.entries(identity.fields).sort(([a], [b]) => a.localeCompare(b)),
+    })).digest("hex");
+}
+export function assertStoredIdentity(credentials, identity) {
+    if (!identity)
+        return;
+    if (!credentials.identity?.values || credentials.identity.binding !== credentialIdentityBinding(credentials, identity) || Object.keys(identity.fields).some((kind) => !Object.hasOwn(credentials.identity.values, kind))) {
+        throw new Error("The saved login has no matching API identity verification. Sign in again to verify the current account and organization.");
+    }
+}
+/** Bind the login to effective nonsecret settings. Scope ordering is irrelevant. */
+export function sessionBinding(config) {
+    const url = (value) => value ? new URL(value).href : null;
+    return createHash("sha256").update(JSON.stringify({
+        apiBaseUrl: url(config.apiBaseUrl), environment: config.environment ?? null, profile: config.profile ?? null,
+        clientId: config.clientId ?? null, issuer: config.issuer ?? null,
+        tokenUrl: url(config.tokenUrl), discoveryUrl: url(config.discoveryUrl), authorizationUrl: url(config.authorizationUrl),
+        scopes: [...new Set(config.scopes ?? [])].sort(), audience: config.audience ?? null, resource: config.resource ?? null,
+        organizationParameter: config.organizationParameter ?? null,
+        identity: config.identity ? { operation: config.identity.operation, fields: Object.entries(config.identity.fields).sort(([a], [b]) => a.localeCompare(b)) } : null,
+    })).digest("hex");
+}
+function code(error) { return error?.code; }
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return code(error) !== "ESRCH";
+    }
+}
+export class CredentialStorageError extends Error {
+}
+/** Private file adapter. All writers (login, refresh and logout) use the same
+ * cross-process lock. Credential storage can be replaced independently of OAuth. */
+export class FileCredentialStore {
+    path;
+    lockTimeoutMs;
+    codec;
+    constructor(path, lockTimeoutMs = 40_000, codec) {
+        this.path = path;
+        this.lockTimeoutMs = lockTimeoutMs;
+        this.codec = codec;
+    }
+    get backend() { return this.codec?.name ?? "private plaintext file"; }
+    /** Check storage access before starting an interactive login. */
+    async prepare() { await this.withLock(async () => { this.codec?.prepare(); }); }
+    read() {
+        try {
+            const encoded = readFileSync(this.path, "utf8");
+            const data = JSON.parse(this.codec ? this.codec.decode(encoded) : encoded);
+            if (!data || typeof data !== "object" || Array.isArray(data))
+                throw new Error();
+            return data;
+        }
+        catch (error) {
+            if (code(error) === "ENOENT")
+                return null;
+            if (error instanceof CredentialStorageError)
+                throw error;
+            throw new Error("Cannot read saved credentials. Check the credential store before logging in again.");
+        }
+    }
+    write(credentials) {
+        if (credentials === null) {
+            rmSync(this.path, { force: true });
+            return;
+        }
+        const temporary = this.path + "." + randomBytes(16).toString("hex") + ".tmp";
+        try {
+            const plaintext = JSON.stringify(credentials, null, 2);
+            writeFileSync(temporary, (this.codec ? this.codec.encode(plaintext) : plaintext) + "\n", { mode: 0o600, flag: "wx", flush: true });
+            renameSync(temporary, this.path);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+    async withLock(work) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const lock = this.path + ".lock";
+        const owner = { pid: process.pid, nonce: randomBytes(16).toString("hex") };
+        const claim = lock + "." + owner.nonce;
+        // Hard-link a complete owner record: no empty-file window if the process dies.
+        writeFileSync(claim, JSON.stringify(owner), { mode: 0o600, flag: "wx" });
+        let acquired = false;
+        const deadline = Date.now() + this.lockTimeoutMs;
+        try {
+            while (!acquired) {
+                try {
+                    linkSync(claim, lock);
+                    acquired = true;
+                }
+                catch (error) {
+                    if (code(error) !== "EEXIST")
+                        throw new Error("Cannot lock the credential store.");
+                    this.recoverDeadOwner(lock);
+                    if (Date.now() >= deadline)
+                        throw new Error("The credential store is busy. Wait for the other login or refresh to finish and retry. If its process stopped, inspect " + lock + ".");
+                    await new Promise((resolve) => setTimeout(resolve, 25));
+                }
+            }
+            return await work({ read: () => this.read(), write: (value) => this.write(value) });
+        }
+        finally {
+            if (acquired)
+                rmSync(lock, { force: true });
+            rmSync(claim, { force: true });
+        }
+    }
+    recoverDeadOwner(lock) {
+        let previous;
+        try {
+            previous = JSON.parse(readFileSync(lock, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!Number.isSafeInteger(previous?.pid) || previous.pid <= 0 || typeof previous.nonce !== "string" || !/^[a-f0-9]{32}$/.test(previous.nonce) || alive(previous.pid))
+            return;
+        // One reclaimer per dead owner. Keep this empty marker: deleting it lets a
+        // delayed contender remove a later owner's lock (the ABA race). A double
+        // crash during reclamation fails closed with the bounded busy diagnostic.
+        const marker = lock + ".reaped-" + previous.nonce;
+        try {
+            closeSync(openSync(marker, "wx", 0o600));
+        }
+        catch {
+            return;
+        }
+        try {
+            const current = JSON.parse(readFileSync(lock, "utf8"));
+            if (current.nonce === previous.nonce)
+                rmSync(lock);
+        }
+        catch { /* another process already completed recovery */ }
+    }
+    async update(change) {
+        await this.withLock(async (store) => { store.write(change(store.read() ?? {})); });
+    }
+    /** Explicit local-only logout can remove an unreadable encrypted session. */
+    async clear() {
+        return this.withLock(async (store) => { const existed = existsSync(this.path); store.write(null); return existed; });
+    }
+    /** Remove under the refresh lock, then revoke the latest token outside it. */
+    async take() {
+        return this.withLock(async (store) => { const current = store.read(); store.write(null); return current; });
+    }
+}
+function validSession(credentials, config, sessionId, allowPending = false) {
+    const session = credentials?.oauth;
+    if (!session || !session.sessionId || session.sessionId !== sessionId)
+        throw new Error("The saved OAuth session changed or was logged out. Run login again and retry the request.");
+    if (session.apiBaseUrl && new URL(session.apiBaseUrl).href !== new URL(config.apiBaseUrl).href)
+        throw new Error("The API destination changed. Log in again.");
+    if (session.issuer && config.issuer && session.issuer !== config.issuer)
+        throw new Error("The configured issuer changed. Log in again.");
+    if (session.configuredClientId !== (config.clientId ?? null))
+        throw new Error("The OAuth client changed. Log in again.");
+    if (!session.binding || session.binding !== sessionBinding(config))
+        throw new Error("The API or OAuth configuration changed. Log in again before using saved credentials.");
+    if (session.refreshPending && !allowPending)
+        throw new Error("The previous OAuth refresh did not finish safely. Log in again; its refresh token will not be reused.");
+    if (typeof session.accessToken !== "string" || !session.accessToken)
+        throw new Error("The saved OAuth session is invalid. Log in again.");
+    assertStoredIdentity(credentials, config.identity);
+    return session;
+}
+/** Re-read on every request attempt; only one process may rotate the token.
+ * A failed or interrupted exchange requires login, since the server may have
+ * consumed its refresh token even when no response reached this process. */
+export async function oauthSessionToken(store, config, sessionId, tokenParams = {}) {
+    const fresh = (session) => session.expiresAt === undefined || (Number.isFinite(session.expiresAt) && session.expiresAt > Date.now() + 60_000);
+    const first = validSession(store.read(), config, sessionId, true);
+    if (!first.refreshPending && fresh(first))
+        return first.accessToken;
+    return store.withLock(async (locked) => {
+        const credentials = locked.read();
+        const session = validSession(credentials, config, sessionId);
+        if (fresh(session))
+            return session.accessToken;
+        if (!session.refreshToken || !session.tokenUrl || !session.clientId)
+            throw new Error("The OAuth session expired and cannot be refreshed. Log in again.");
+        const endpoint = new URL(session.tokenUrl);
+        if ((endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname))) || endpoint.username || endpoint.password || endpoint.hash)
+            throw new Error("The OAuth token endpoint requires HTTPS; loopback HTTP is allowed for development.");
+        locked.write({ ...credentials, oauth: { ...session, refreshPending: true } });
+        try {
+            const response = await oauthJsonRequest(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+                body: new URLSearchParams({ ...tokenParams, grant_type: "refresh_token", refresh_token: session.refreshToken, client_id: session.clientId }),
+            });
+            const body = response.data;
+            if (response.status !== 200 || !body || typeof body.access_token !== "string" || !body.access_token || typeof body.token_type !== "string" || body.token_type.toLowerCase() !== "bearer")
+                throw new Error();
+            if (body.expires_in !== undefined && (typeof body.expires_in !== "number" || !Number.isFinite(body.expires_in) || body.expires_in <= 0))
+                throw new Error();
+            if (body.refresh_token !== undefined && (typeof body.refresh_token !== "string" || !body.refresh_token))
+                throw new Error();
+            if (body.scope !== undefined && typeof body.scope !== "string")
+                throw new Error();
+            const next = {
+                ...session, accessToken: body.access_token, refreshToken: body.refresh_token ?? session.refreshToken,
+                expiresAt: typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : undefined,
+                ...(typeof body.scope === "string" ? { scopes: body.scope.split(/\s+/).filter(Boolean) } : {}), refreshPending: undefined,
+            };
+            let identity = credentials?.identity;
+            if (config.identity) {
+                if (!config.verifyIdentity || !identity)
+                    throw new Error();
+                const verified = await config.verifyIdentity(next.accessToken);
+                assertApiIdentity(identity.values, verified.values);
+                identity = { ...identity, ...verified };
+            }
+            locked.write({ ...credentials, oauth: next, ...(identity ? { identity } : {}) });
+            return next.accessToken;
+        }
+        catch {
+            // Never expose an error body, a refresh token, or fetch's nested cause.
+            throw new Error("The OAuth session could not be refreshed safely. Log in again.");
+        }
+    });
+}

package/dist/ops.d.ts

@@ -23,6 +23,16 @@ export interface ParamSpec {
     description?: string;
     /** Settable once on the client (globals option); optional per call. */
     global?: boolean;
+    /** False opts out. Otherwise exact human references are resolved through
+     * this one read operation before the requested call. */
+    resolve?: false | {
+        via: string;
+        match: string[];
+        id: string;
+        idPattern?: string;
+        filterParam?: string;
+        inferred?: boolean;
+    };
 }
 export interface OpSpec {
     resource: string;
@@ -85,6 +95,9 @@ export interface OpSpec {
     /** The spec's security requirement: "required" fails fast without a
      * credential; "none" works anonymously; "optional" is either. */
     auth: "required" | "optional" | "none";
+    security?: Record<string, string[]>[];
+    /** Complete credential-option combinations for this operation. */
+    credentialOptions?: string[][];
     /** Whether calling this operation only reads, writes, or destroys state. */
     safety: "read" | "write" | "destructive";
     params: ParamSpec[];
@@ -99,7 +112,7 @@ export declare const OPS: OpSpec[];
 /** Operations present in the API Definition but omitted by this
  * generation's operation cap. Kept deliberately small: enough for honest
  * discovery and PLAN_LIMIT errors, never enough to call an absent method. */
-export type OmittedOpSpec = Pick<OpSpec, "resource" | "method" | "command" | "commandAlias" | "tool" | "httpMethod" | "path" | "summary" | "description" | "toolDescription" | "paginated" | "select" | "safety" | "auth" | "params" | "inputSchema">;
+export type OmittedOpSpec = Pick<OpSpec, "resource" | "method" | "command" | "commandAlias" | "tool" | "httpMethod" | "path" | "summary" | "description" | "toolDescription" | "paginated" | "select" | "safety" | "auth" | "security" | "params" | "inputSchema">;
 export declare const OMITTED_OPS: OmittedOpSpec[];
 /** Parameters settable once on the client (globals option): CLI/MCP fill
  * them from flags or environment; the SDK falls back per request. */

package/dist/ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"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"}