@frontmcp/sdk 0.2.5 → 0.3.0

package/src/auth/oauth/flows/oauth.par.flow.d.ts

@@ -0,0 +1,27 @@
+export {};
+/**
+ * Pushed Authorization Requests (PAR) — POST /oauth/par
+ *
+ * Who calls: Client (before sending user to /authorize).
+ *
+ * Purpose: Client uploads the full authorization request; you return a request_uri the client forwards to /authorize.
+ *
+ * Why: Prevents parameter tampering and URL-length issues; recommended for high-security setups and with DPoP/JAR.
+ */
+/**
+ * Typical parameter shapes
+
+ * /oauth/par (POST): same authz params as /authorize (client-authenticated), returns { request_uri, expires_in }
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */

package/src/auth/oauth/flows/oauth.par.flow.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Pushed Authorization Requests (PAR) — POST /oauth/par
+ *
+ * Who calls: Client (before sending user to /authorize).
+ *
+ * Purpose: Client uploads the full authorization request; you return a request_uri the client forwards to /authorize.
+ *
+ * Why: Prevents parameter tampering and URL-length issues; recommended for high-security setups and with DPoP/JAR.
+ */
+/**
+ * Typical parameter shapes
+
+ * /oauth/par (POST): same authz params as /authorize (client-authenticated), returns { request_uri, expires_in }
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+//# sourceMappingURL=oauth.par.flow.js.map

package/src/auth/oauth/flows/oauth.par.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.par.flow.js","sourceRoot":"","sources":["../../../../../src/auth/oauth/flows/oauth.par.flow.ts"],"names":[],"mappings":";;AAAA;;;;;;;;GAQG;AACH;;;;GAIG;AACH;;;;;;;;;;;GAWG","sourcesContent":["/**\n * Pushed Authorization Requests (PAR) — POST /oauth/par\n *\n * Who calls: Client (before sending user to /authorize).\n *\n * Purpose: Client uploads the full authorization request; you return a request_uri the client forwards to /authorize.\n *\n * Why: Prevents parameter tampering and URL-length issues; recommended for high-security setups and with DPoP/JAR.\n */\n/**\n * Typical parameter shapes\n\n * /oauth/par (POST): same authz params as /authorize (client-authenticated), returns { request_uri, expires_in }\n */\n/**\n * Quick checklist (security & correctness)\n * - PKCE (S256) required for public clients (and basically for all).\n * - Use authorization code grant only (no implicit/hybrid).\n * - Rotate refresh tokens and bind them to client + user + scopes.\n * - Prefer private_key_jwt or mTLS for confidential clients.\n * - PAR + JAR recommended for higher security.\n * - Consider DPoP (proof-of-possession) to reduce token replay.\n * - Keep codes very short-lived (e.g., ≤60 s) and single-use.\n * - Publish discovery and JWKS, rotate keys safely.\n * - Decide JWT vs opaque access tokens; provide introspection if opaque.\n */\n"]}

package/src/auth/oauth/flows/oauth.revoke.flow.d.ts

@@ -0,0 +1,25 @@
+export {};
+/**
+ * Token Revocation — POST /oauth/revoke
+ *
+ * Who calls: Client.
+ *
+ * Purpose: Invalidate an access or refresh token early (RFC 7009).
+ */
+/**
+ * Typical parameter shapes
+ *
+ * /oauth/revoke (POST): token, token_type_hint=access_token|refresh_token
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */

package/src/auth/oauth/flows/oauth.revoke.flow.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Token Revocation — POST /oauth/revoke
+ *
+ * Who calls: Client.
+ *
+ * Purpose: Invalidate an access or refresh token early (RFC 7009).
+ */
+/**
+ * Typical parameter shapes
+ *
+ * /oauth/revoke (POST): token, token_type_hint=access_token|refresh_token
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+//# sourceMappingURL=oauth.revoke.flow.js.map

package/src/auth/oauth/flows/oauth.revoke.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.revoke.flow.js","sourceRoot":"","sources":["../../../../../src/auth/oauth/flows/oauth.revoke.flow.ts"],"names":[],"mappings":";;AAAA;;;;;;GAMG;AACH;;;;GAIG;AACH;;;;;;;;;;;GAWG","sourcesContent":["/**\n * Token Revocation — POST /oauth/revoke\n *\n * Who calls: Client.\n *\n * Purpose: Invalidate an access or refresh token early (RFC 7009).\n */\n/**\n * Typical parameter shapes\n *\n * /oauth/revoke (POST): token, token_type_hint=access_token|refresh_token\n */\n/**\n * Quick checklist (security & correctness)\n * - PKCE (S256) required for public clients (and basically for all).\n * - Use authorization code grant only (no implicit/hybrid).\n * - Rotate refresh tokens and bind them to client + user + scopes.\n * - Prefer private_key_jwt or mTLS for confidential clients.\n * - PAR + JAR recommended for higher security.\n * - Consider DPoP (proof-of-possession) to reduce token replay.\n * - Keep codes very short-lived (e.g., ≤60 s) and single-use.\n * - Publish discovery and JWKS, rotate keys safely.\n * - Decide JWT vs opaque access tokens; provide introspection if opaque.\n */\n"]}

package/src/auth/oauth/flows/oauth.token.flow.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Token Endpoint — POST /oauth/token
+ *
+ * Who calls: Client (server-to-server).
+ *
+ * When: After getting the code (or for refresh).
+ *
+ * Purpose: Exchange authorization code + PKCE verifier for access token (and optional refresh token), or refresh an access token.
+ */
+/**
+ * Typical parameter shapes
+ *
+ * /oauth/token (POST, application/x-www-form-urlencoded)
+ *
+ * For code exchange: grant_type=authorization_code, code, redirect_uri, client_id (and auth), code_verifier
+ *
+ * For refresh: grant_type=refresh_token, refresh_token, client_id (and auth)
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+export {};
+/**
+ *
+ * OAuth 2.0 Device Authorization Grant (“device code flow”)
+ * Who does what (at a glance)
+ *
+ * Device/TV/CLI (no browser)
+ * Calls POST /oauth/device_authorization, shows the user a code + URL, and polls POST /oauth/token.
+ *
+ * User (on phone/laptop browser)
+ * Visits the given verification_uri and authenticates using your normal OAuth login (whatever you already have). No new UI required beyond two tiny endpoints.
+ *
+ * Auth Server (you)
+ * Stores the device transaction and, after the user authenticates, marks it as approved so the device’s /oauth/token polling succeeds.
+ *
+ * Endpoints you need (only two “new” ones)
+ *
+ * POST /oauth/device_authorization ✅ (device calls)
+ *
+ * POST /oauth/token with grant urn:ietf:params:oauth:grant-type:device_code ✅ (device polls)
+ *
+ * GET /activate ➜ “UI handler” (user lands here from verification_uri — this just redirects into your existing /oauth/authorize)
+ *
+ * GET /activate/callback ➜ “UI handler” (your existing flow returns here after the user logs in; you flip the device record to approved and show a basic “All set” page)
+ *
+ * That’s it. No pages with complex consent screens are required; reuse your normal /oauth/authorize
+ */

package/src/auth/oauth/flows/oauth.token.flow.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Token Endpoint — POST /oauth/token
+ *
+ * Who calls: Client (server-to-server).
+ *
+ * When: After getting the code (or for refresh).
+ *
+ * Purpose: Exchange authorization code + PKCE verifier for access token (and optional refresh token), or refresh an access token.
+ */
+/**
+ * Typical parameter shapes
+ *
+ * /oauth/token (POST, application/x-www-form-urlencoded)
+ *
+ * For code exchange: grant_type=authorization_code, code, redirect_uri, client_id (and auth), code_verifier
+ *
+ * For refresh: grant_type=refresh_token, refresh_token, client_id (and auth)
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ *
+ * OAuth 2.0 Device Authorization Grant (“device code flow”)
+ * Who does what (at a glance)
+ *
+ * Device/TV/CLI (no browser)
+ * Calls POST /oauth/device_authorization, shows the user a code + URL, and polls POST /oauth/token.
+ *
+ * User (on phone/laptop browser)
+ * Visits the given verification_uri and authenticates using your normal OAuth login (whatever you already have). No new UI required beyond two tiny endpoints.
+ *
+ * Auth Server (you)
+ * Stores the device transaction and, after the user authenticates, marks it as approved so the device’s /oauth/token polling succeeds.
+ *
+ * Endpoints you need (only two “new” ones)
+ *
+ * POST /oauth/device_authorization ✅ (device calls)
+ *
+ * POST /oauth/token with grant urn:ietf:params:oauth:grant-type:device_code ✅ (device polls)
+ *
+ * GET /activate ➜ “UI handler” (user lands here from verification_uri — this just redirects into your existing /oauth/authorize)
+ *
+ * GET /activate/callback ➜ “UI handler” (your existing flow returns here after the user logs in; you flip the device record to approved and show a basic “All set” page)
+ *
+ * That’s it. No pages with complex consent screens are required; reuse your normal /oauth/authorize
+ */
+//# sourceMappingURL=oauth.token.flow.js.map

package/src/auth/oauth/flows/oauth.token.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.token.flow.js","sourceRoot":"","sources":["../../../../../src/auth/oauth/flows/oauth.token.flow.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AACH;;;;;;;;GAQG;AACH;;;;;;;;;;;GAWG;;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG","sourcesContent":["/**\n * Token Endpoint — POST /oauth/token\n *\n * Who calls: Client (server-to-server).\n *\n * When: After getting the code (or for refresh).\n *\n * Purpose: Exchange authorization code + PKCE verifier for access token (and optional refresh token), or refresh an access token.\n */\n/**\n * Typical parameter shapes\n *\n * /oauth/token (POST, application/x-www-form-urlencoded)\n *\n * For code exchange: grant_type=authorization_code, code, redirect_uri, client_id (and auth), code_verifier\n *\n * For refresh: grant_type=refresh_token, refresh_token, client_id (and auth)\n */\n/**\n * Quick checklist (security & correctness)\n * - PKCE (S256) required for public clients (and basically for all).\n * - Use authorization code grant only (no implicit/hybrid).\n * - Rotate refresh tokens and bind them to client + user + scopes.\n * - Prefer private_key_jwt or mTLS for confidential clients.\n * - PAR + JAR recommended for higher security.\n * - Consider DPoP (proof-of-possession) to reduce token replay.\n * - Keep codes very short-lived (e.g., ≤60 s) and single-use.\n * - Publish discovery and JWKS, rotate keys safely.\n * - Decide JWT vs opaque access tokens; provide introspection if opaque.\n */\n\n/**\n *\n * OAuth 2.0 Device Authorization Grant (“device code flow”)\n * Who does what (at a glance)\n *\n * Device/TV/CLI (no browser)\n * Calls POST /oauth/device_authorization, shows the user a code + URL, and polls POST /oauth/token.\n *\n * User (on phone/laptop browser)\n * Visits the given verification_uri and authenticates using your normal OAuth login (whatever you already have). No new UI required beyond two tiny endpoints.\n *\n * Auth Server (you)\n * Stores the device transaction and, after the user authenticates, marks it as approved so the device’s /oauth/token polling succeeds.\n *\n * Endpoints you need (only two “new” ones)\n *\n * POST /oauth/device_authorization ✅ (device calls)\n *\n * POST /oauth/token with grant urn:ietf:params:oauth:grant-type:device_code ✅ (device polls)\n *\n * GET /activate ➜ “UI handler” (user lands here from verification_uri — this just redirects into your existing /oauth/authorize)\n *\n * GET /activate/callback ➜ “UI handler” (your existing flow returns here after the user logs in; you flip the device record to approved and show a basic “All set” page)\n *\n * That’s it. No pages with complex consent screens are required; reuse your normal /oauth/authorize\n */\n"]}

package/src/auth/oauth/flows/oauth.userinfo.flow.d.ts

@@ -0,0 +1,22 @@
+export {};
+/**
+ * UserInfo (OIDC) — GET/POST /oauth/userinfo (Only if you add OpenID Connect)
+ *
+ * Who calls: Client with access token.
+ *
+ * Purpose: Return standard user claims.
+ *
+ * Note: Requires the openid scope; if you do OIDC, also expose /.well-known/openid-configuration (separate from OAuth discovery).
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */

package/src/auth/oauth/flows/oauth.userinfo.flow.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * UserInfo (OIDC) — GET/POST /oauth/userinfo (Only if you add OpenID Connect)
+ *
+ * Who calls: Client with access token.
+ *
+ * Purpose: Return standard user claims.
+ *
+ * Note: Requires the openid scope; if you do OIDC, also expose /.well-known/openid-configuration (separate from OAuth discovery).
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+//# sourceMappingURL=oauth.userinfo.flow.js.map

package/src/auth/oauth/flows/oauth.userinfo.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.userinfo.flow.js","sourceRoot":"","sources":["../../../../../src/auth/oauth/flows/oauth.userinfo.flow.ts"],"names":[],"mappings":";;AAAA;;;;;;;;GAQG;AACH;;;;;;;;;;;GAWG","sourcesContent":["/**\n * UserInfo (OIDC) — GET/POST /oauth/userinfo (Only if you add OpenID Connect)\n *\n * Who calls: Client with access token.\n *\n * Purpose: Return standard user claims.\n *\n * Note: Requires the openid scope; if you do OIDC, also expose /.well-known/openid-configuration (separate from OAuth discovery).\n */\n/**\n * Quick checklist (security & correctness)\n * - PKCE (S256) required for public clients (and basically for all).\n * - Use authorization code grant only (no implicit/hybrid).\n * - Rotate refresh tokens and bind them to client + user + scopes.\n * - Prefer private_key_jwt or mTLS for confidential clients.\n * - PAR + JAR recommended for higher security.\n * - Consider DPoP (proof-of-possession) to reduce token replay.\n * - Keep codes very short-lived (e.g., ≤60 s) and single-use.\n * - Publish discovery and JWKS, rotate keys safely.\n * - Decide JWT vs opaque access tokens; provide introspection if opaque.\n */\n"]}

package/src/auth/oauth/flows/oidc.logout.flow.d.ts

@@ -0,0 +1,18 @@
+export {};
+/**
+ * Session/Logout (OIDC) — e.g., GET /oidc/logout (front-/back-channel variants)
+ *
+ * Purpose: Coordinate RP logout if you support OIDC logout.
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */

package/src/auth/oauth/flows/oidc.logout.flow.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Session/Logout (OIDC) — e.g., GET /oidc/logout (front-/back-channel variants)
+ *
+ * Purpose: Coordinate RP logout if you support OIDC logout.
+ */
+/**
+ * Quick checklist (security & correctness)
+ * - PKCE (S256) required for public clients (and basically for all).
+ * - Use authorization code grant only (no implicit/hybrid).
+ * - Rotate refresh tokens and bind them to client + user + scopes.
+ * - Prefer private_key_jwt or mTLS for confidential clients.
+ * - PAR + JAR recommended for higher security.
+ * - Consider DPoP (proof-of-possession) to reduce token replay.
+ * - Keep codes very short-lived (e.g., ≤60 s) and single-use.
+ * - Publish discovery and JWKS, rotate keys safely.
+ * - Decide JWT vs opaque access tokens; provide introspection if opaque.
+ */
+//# sourceMappingURL=oidc.logout.flow.js.map

package/src/auth/oauth/flows/oidc.logout.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.logout.flow.js","sourceRoot":"","sources":["../../../../../src/auth/oauth/flows/oidc.logout.flow.ts"],"names":[],"mappings":";;AAAA;;;;GAIG;AACH;;;;;;;;;;;GAWG","sourcesContent":["/**\n * Session/Logout (OIDC) — e.g., GET /oidc/logout (front-/back-channel variants)\n *\n * Purpose: Coordinate RP logout if you support OIDC logout.\n */\n/**\n * Quick checklist (security & correctness)\n * - PKCE (S256) required for public clients (and basically for all).\n * - Use authorization code grant only (no implicit/hybrid).\n * - Rotate refresh tokens and bind them to client + user + scopes.\n * - Prefer private_key_jwt or mTLS for confidential clients.\n * - PAR + JAR recommended for higher security.\n * - Consider DPoP (proof-of-possession) to reduce token replay.\n * - Keep codes very short-lived (e.g., ≤60 s) and single-use.\n * - Publish discovery and JWKS, rotate keys safely.\n * - Decide JWT vs opaque access tokens; provide introspection if opaque.\n */\n"]}

package/src/auth/path.utils.d.ts

@@ -0,0 +1,20 @@
+import { ServerRequest } from '../common';
+export declare function trimSlashes(s: string): string;
+/** Normalize entryPath (gateway prefix) to "" or "/mcp" */
+export declare function normalizeEntryPrefix(entryPath?: string): string;
+/** Normalize a scope base (per-app or per-auth) to "" or "/app1" */
+export declare function normalizeScopeBase(scopeBase?: string): string;
+/** Join URL path segments with a single slash and no trailing slash */
+export declare function joinPath(...parts: string[]): string;
+export declare function getRequestBaseUrl(req: ServerRequest, entryPath?: string): string;
+export declare function computeIssuer(req: ServerRequest, entryPath: string, scopeBase: string): string;
+export declare function computeResource(req: ServerRequest, entryPath: string, scopeBase: string): string;
+/** Derive a safe provider id from a URL when no id is provided. */
+export declare function urlToSafeId(url: string): string | undefined;
+/**
+ * Build all path variants for a given well-known name:
+ * - reversed under root: /.well-known/<name><entryPrefix><scopeBase>
+ * - in prefix root: <entryPrefix>/.well-known/<name><scopeBase>
+ * - in prefix + scope: <entryPrefix><scopeBase>/.well-known/<name>
+ */
+export declare function makeWellKnownPaths(name: string, entryPrefix: string, scopeBase?: string): Set<string>;

package/src/auth/path.utils.js

@@ -0,0 +1,71 @@
+"use strict";
+// auth/path.utils.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimSlashes = trimSlashes;
+exports.normalizeEntryPrefix = normalizeEntryPrefix;
+exports.normalizeScopeBase = normalizeScopeBase;
+exports.joinPath = joinPath;
+exports.getRequestBaseUrl = getRequestBaseUrl;
+exports.computeIssuer = computeIssuer;
+exports.computeResource = computeResource;
+exports.urlToSafeId = urlToSafeId;
+exports.makeWellKnownPaths = makeWellKnownPaths;
+function trimSlashes(s) {
+    return (s ?? '').replace(/^\/+|\/+$/g, '');
+}
+/** Normalize entryPath (gateway prefix) to "" or "/mcp" */
+function normalizeEntryPrefix(entryPath) {
+    const t = trimSlashes(entryPath ?? '');
+    return t ? `/${t}` : '';
+}
+/** Normalize a scope base (per-app or per-auth) to "" or "/app1" */
+function normalizeScopeBase(scopeBase) {
+    const t = trimSlashes(scopeBase ?? '');
+    return t ? `/${t}` : '';
+}
+/** Join URL path segments with a single slash and no trailing slash */
+function joinPath(...parts) {
+    const cleaned = parts.map((p) => trimSlashes(p)).filter(Boolean);
+    return cleaned.length ? `/${cleaned.join('/')}` : '';
+}
+function getRequestBaseUrl(req, entryPath) {
+    const proto = req.headers['x-forwarded-proto'] || req.protocol || 'http';
+    const host = req.headers['x-forwarded-host'] || req.headers['host'];
+    return `${proto}://${host}${entryPath ?? ''}`;
+}
+function computeIssuer(req, entryPath, scopeBase) {
+    const entryPrefix = normalizeEntryPrefix(entryPath);
+    const scope = normalizeScopeBase(scopeBase);
+    return `${getRequestBaseUrl(req)}${entryPrefix}${scope}`;
+}
+function computeResource(req, entryPath, scopeBase) {
+    const entryPrefix = normalizeEntryPrefix(entryPath);
+    const scope = normalizeScopeBase(scopeBase);
+    return `${getRequestBaseUrl(req)}${entryPrefix}${scope}`;
+}
+/** Derive a safe provider id from a URL when no id is provided. */
+function urlToSafeId(url) {
+    try {
+        const u = new URL(url);
+        const raw = (u.host + (u.pathname && u.pathname !== '/' ? u.pathname : '')).replace(/\/+$/, '');
+        return trimSlashes(raw).replace(/[^a-zA-Z0-9_-]/g, '-');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build all path variants for a given well-known name:
+ * - reversed under root: /.well-known/<name><entryPrefix><scopeBase>
+ * - in prefix root: <entryPrefix>/.well-known/<name><scopeBase>
+ * - in prefix + scope: <entryPrefix><scopeBase>/.well-known/<name>
+ */
+function makeWellKnownPaths(name, entryPrefix, scopeBase = '') {
+    const prefix = normalizeEntryPrefix(entryPrefix);
+    const scope = normalizeScopeBase(scopeBase);
+    const reversed = joinPath('.well-known', name) + `${prefix}${scope}`; // /.well-known/name + /mcp/app1
+    const inPrefixRoot = `${prefix}${joinPath('.well-known', name)}${scope}`; // /mcp/.well-known/name + /app1
+    const inPrefixScope = `${prefix}${scope}${joinPath('.well-known', name)}`; // /mcp/app1/.well-known/name
+    return new Set([reversed, inPrefixRoot, inPrefixScope]);
+}
+//# sourceMappingURL=path.utils.js.map

package/src/auth/path.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.utils.js","sourceRoot":"","sources":["../../../src/auth/path.utils.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/path.utils.ts\n\nimport { ServerRequest } from '../common';\n\nexport function trimSlashes(s: string) {\n  return (s ?? '').replace(/^\\/+|\\/+$/g, '');\n}\n\n/** Normalize entryPath (gateway prefix) to \"\" or \"/mcp\" */\nexport function normalizeEntryPrefix(entryPath?: string): string {\n  const t = trimSlashes(entryPath ?? '');\n  return t ? `/${t}` : '';\n}\n\n/** Normalize a scope base (per-app or per-auth) to \"\" or \"/app1\" */\nexport function normalizeScopeBase(scopeBase?: string): string {\n  const t = trimSlashes(scopeBase ?? '');\n  return t ? `/${t}` : '';\n}\n\n/** Join URL path segments with a single slash and no trailing slash */\nexport function joinPath(...parts: string[]) {\n  const cleaned = parts.map((p) => trimSlashes(p)).filter(Boolean);\n  return cleaned.length ? `/${cleaned.join('/')}` : '';\n}\n\n\nexport function getRequestBaseUrl(req: ServerRequest, entryPath?: string) {\n  const proto = (req.headers['x-forwarded-proto'] as string) || (req as any).protocol || 'http';\n  const host = (req.headers['x-forwarded-host'] as string) || req.headers['host'];\n  return `${proto}://${host}${entryPath ?? ''}`;\n}\n\nexport function computeIssuer(req: ServerRequest, entryPath: string, scopeBase: string) {\n  const entryPrefix = normalizeEntryPrefix(entryPath);\n  const scope = normalizeScopeBase(scopeBase);\n  return `${getRequestBaseUrl(req)}${entryPrefix}${scope}`;\n}\n\nexport function computeResource(req: ServerRequest, entryPath: string, scopeBase: string) {\n  const entryPrefix = normalizeEntryPrefix(entryPath);\n  const scope = normalizeScopeBase(scopeBase);\n  return `${getRequestBaseUrl(req)}${entryPrefix}${scope}`;\n}\n\n/** Derive a safe provider id from a URL when no id is provided. */\nexport function urlToSafeId(url: string): string | undefined {\n  try {\n    const u = new URL(url);\n    const raw = (u.host + (u.pathname && u.pathname !== '/' ? u.pathname : '')).replace(/\\/+$/, '');\n    return trimSlashes(raw).replace(/[^a-zA-Z0-9_-]/g, '-');\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Build all path variants for a given well-known name:\n * - reversed under root: /.well-known/<name><entryPrefix><scopeBase>\n * - in prefix root: <entryPrefix>/.well-known/<name><scopeBase>\n * - in prefix + scope: <entryPrefix><scopeBase>/.well-known/<name>\n */\nexport function makeWellKnownPaths(name: string, entryPrefix: string, scopeBase = '') {\n  const prefix = normalizeEntryPrefix(entryPrefix);\n  const scope = normalizeScopeBase(scopeBase);\n  const reversed = joinPath('.well-known', name) + `${prefix}${scope}`; // /.well-known/name + /mcp/app1\n  const inPrefixRoot = `${prefix}${joinPath('.well-known', name)}${scope}`; // /mcp/.well-known/name + /app1\n  const inPrefixScope = `${prefix}${scope}${joinPath('.well-known', name)}`; // /mcp/app1/.well-known/name\n  return new Set([reversed, inPrefixRoot, inPrefixScope]);\n}\n"]}

package/src/auth/session/index.d.ts

@@ -0,0 +1,4 @@
+export { SessionService } from './session.service';
+export type { CreateSessionArgs } from './session.types';
+export { isSoonExpiringProvider } from './token.refresh';
+export { Session } from './record/session.base';

package/src/auth/session/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = exports.isSoonExpiringProvider = exports.SessionService = void 0;
+var session_service_1 = require("./session.service");
+Object.defineProperty(exports, "SessionService", { enumerable: true, get: function () { return session_service_1.SessionService; } });
+var token_refresh_1 = require("./token.refresh");
+Object.defineProperty(exports, "isSoonExpiringProvider", { enumerable: true, get: function () { return token_refresh_1.isSoonExpiringProvider; } });
+var session_base_1 = require("./record/session.base");
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_base_1.Session; } });
+//# sourceMappingURL=index.js.map

package/src/auth/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/auth/session/index.ts"],"names":[],"mappings":";;;AAAA,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AAEvB,iDAAyD;AAAhD,uHAAA,sBAAsB,OAAA;AAE/B,sDAAgD;AAAvC,uGAAA,OAAO,OAAA","sourcesContent":["export { SessionService } from './session.service';\nexport type { CreateSessionArgs } from './session.types';\nexport { isSoonExpiringProvider } from './token.refresh';\n\nexport { Session } from './record/session.base';\n"]}

package/src/auth/session/record/session.base.d.ts

@@ -0,0 +1,103 @@
+import type { ProviderSnapshot, SessionMode } from '../session.types';
+import { Scope } from '../../../scope';
+export interface BaseCreateCtx {
+    id: string;
+    sessionId?: string;
+    scope: Scope;
+    issuer: string;
+    token: string;
+    user: SessionUser;
+    claims?: SessionClaims;
+    createdAt?: number;
+    authorizedProviders?: Record<string, ProviderSnapshot>;
+    authorizedProviderIds?: string[];
+    authorizedApps?: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    authorizedAppIds?: string[];
+    authorizedResources?: string[];
+    scopes?: string[];
+    authorizedTools?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    authorizedToolIds?: string[];
+    authorizedPrompts?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    authorizedPromptIds?: string[];
+}
+export interface SessionUser {
+    sub?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+}
+export interface SessionClaims {
+    [key: string]: any;
+}
+export declare abstract class Session {
+    #private;
+    readonly id: string;
+    abstract readonly mode: SessionMode;
+    readonly createdAt: number;
+    readonly scopeId: string;
+    readonly user: SessionUser;
+    readonly claims?: Record<string, unknown>;
+    /** Epoch millis when the bearer token expires (if available). */
+    readonly expiresAt?: number;
+    readonly authorizedProviders: Record<string, ProviderSnapshot>;
+    readonly authorizedProviderIds: string[];
+    readonly authorizedApps: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    readonly authorizedAppIds: string[];
+    readonly authorizedResources: string[];
+    readonly scopes?: string[];
+    readonly authorizedTools?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    readonly authorizedToolIds?: string[];
+    readonly authorizedPrompts?: Record<string, {
+        executionPath: [string, string];
+        details?: Record<string, any>;
+    }>;
+    readonly authorizedPromptIds?: string[];
+    protected token: string;
+    protected constructor(ctx: BaseCreateCtx);
+    /**
+     * Get the scope associated with this session.
+     * Can be used by subclasses to implement custom scope handling.
+     * @protected
+     */
+    protected get scope(): Scope;
+    get issuer(): string;
+    getTransportSessionId(): Promise<string>;
+    /**
+     * Get the access token for a given provider.
+     * Must be implemented in subclasses based on session topology.
+     * @protected
+     * @param providerId
+     */
+    abstract getToken(providerId?: string): Promise<string> | string;
+    scoped(allowed: string | string[] | ((id: string) => boolean)): SessionView;
+}
+export declare class SessionView {
+    private readonly parent;
+    private readonly allow;
+    constructor(parent: Session, allow: (id: string) => boolean);
+    get id(): string;
+    get mode(): SessionMode;
+    get user(): SessionUser;
+    get claims(): Record<string, unknown> | undefined;
+    get authorizedApps(): Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    getToken(providerId: string): Promise<string>;
+    get transportId(): () => Promise<string>;
+}