@absolutejs/auth 0.56.13 → 0.56.14

package/dist/server.js

@@ -3206,6 +3206,95 @@ var agentAuthContextPlugin = (config) => new Elysia2({
   }
 })).as("global");
 
+// src/agents/oauthGuide.ts
+var DEFAULT_GUIDE_ROUTE = "/auth.md";
+var secureUrl = (value, label) => {
+  const url = new URL(value);
+  const loopback = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  if (url.protocol !== "https:" && !loopback)
+    throw new Error(`${label} must use HTTPS outside loopback development`);
+  if (url.username || url.password || url.hash)
+    throw new Error(`${label} cannot contain credentials or a fragment`);
+  return url.toString();
+};
+var agentOAuthGuideRoute = (config) => config.route ?? DEFAULT_GUIDE_ROUTE;
+var agentOAuthGuideUrl = (config) => new URL(agentOAuthGuideRoute(config), secureUrl(config.authorizationServer, "OAuth authorization server")).toString();
+var normalizedResources = (config) => {
+  if (config.resources.length === 0)
+    throw new Error("Agent OAuth guide requires at least one resource");
+  const resources = config.resources.map((resource) => ({
+    metadataUrl: secureUrl(resource.metadataUrl, "Protected-resource metadata URL"),
+    name: resource.name.trim(),
+    resource: secureUrl(resource.resource, "OAuth protected resource"),
+    scopes: [
+      ...new Set(resource.scopes.map((scope) => scope.trim()))
+    ].filter(Boolean)
+  }));
+  if (resources.some(({ name, scopes }) => !name || scopes.length === 0))
+    throw new Error("Every agent OAuth guide resource requires a name and at least one scope");
+  if (new Set(resources.map(({ resource }) => resource)).size !== resources.length)
+    throw new Error("Agent OAuth guide resources must be unique");
+  return resources;
+};
+var resourceSections = (resources) => resources.map((resource) => `### ${resource.name}
+
+- Protected resource: \`${resource.resource}\`
+- Metadata: ${resource.metadataUrl}
+- Allowed scopes: ${resource.scopes.map((scope) => `\`${scope}\``).join(", ")}
+`).join(`
+`);
+var generateAgentOAuthGuide = (config) => {
+  if (!config.serviceName.trim())
+    throw new Error("Agent OAuth guide requires a service name");
+  const authorizationServer = secureUrl(config.authorizationServer, "OAuth authorization server");
+  const resources = normalizedResources(config);
+  const authorizationMetadata = new URL("/.well-known/oauth-authorization-server", authorizationServer).toString();
+  return `# OAuth access for ${config.serviceName.trim()}
+
+This guide is the agent-readable companion to the service's standards-based
+OAuth metadata. Discovery metadata is authoritative. Do not infer endpoints,
+scopes, audiences, or capabilities that are not advertised.
+
+## 1. Discover
+
+Fetch the protected-resource metadata for the exact interface you intend to
+use, then fetch the authorization-server metadata at
+${authorizationMetadata}.
+
+${resourceSections(resources)}
+## 2. Register the OAuth client
+
+Use an existing registered client or the advertised \`registration_endpoint\`.
+Request only scopes listed for the selected protected resource. Never register
+redirect URIs, grant types, or authentication methods the metadata rejects.
+
+## 3. Obtain user delegation
+
+For an interactive user, use authorization code with PKCE. For a device or
+headless client, use the device authorization grant only when
+\`device_authorization_endpoint\` is advertised. Send the selected protected
+resource as the OAuth \`resource\` value and show the exact requested scopes to
+the user before consent.
+
+## 4. Call the selected interface
+
+Present the access token in the Authorization header. The token must name the
+selected resource as its audience and contain the required scope. A token for
+one resource or transport is not authority for another.
+
+## Safety
+
+- Never ask a user to send a password, passkey response, MFA code, device code,
+  authorization code, client secret, refresh token, or access token to the
+  agent or place one in model context.
+- Stop on issuer, signature, audience, expiry, delegation, or scope failure.
+- Treat consent denial, revocation, and disabled interfaces as final until the
+  user explicitly starts a new authorization flow.
+- Discovery is not authorization, and this guide grants no capability by
+  itself.
+`;
+};
+
 // src/agents/registration.ts
 init_constants();
 init_crypto();
@@ -3317,7 +3406,7 @@ var AGENT_IDENTITY_ASSERTION_TYPE = "urn:ietf:params:oauth:token-type:id-jag";
 var DEFAULT_IDENTITY_ROUTE = "/agent/identity";
 var DEFAULT_CLAIM_ROUTE = "/agent/identity/claim";
 var DEFAULT_COMPLETE_ROUTE = "/agent/identity/claim/complete";
-var DEFAULT_GUIDE_ROUTE = "/auth.md";
+var DEFAULT_GUIDE_ROUTE2 = "/auth.md";
 var DEFAULT_CLAIM_TTL_MS = 24 * 60 * MILLISECONDS_IN_A_MINUTE;
 var DEFAULT_ATTEMPT_TTL_MS = 10 * MILLISECONDS_IN_A_MINUTE;
 var DEFAULT_ASSERTION_TTL_MS = 60 * MILLISECONDS_IN_A_MINUTE;
@@ -3352,7 +3441,7 @@ var agentRegistrationEndpoints = (config) => {
   return {
     claimEndpoint: new URL(registration.claimRoute ?? DEFAULT_CLAIM_ROUTE, base).toString(),
     completeEndpoint: new URL(registration.completeRoute ?? DEFAULT_COMPLETE_ROUTE, base).toString(),
-    guide: new URL(registration.guideRoute ?? DEFAULT_GUIDE_ROUTE, base).toString(),
+    guide: new URL(registration.guideRoute ?? DEFAULT_GUIDE_ROUTE2, base).toString(),
     identityEndpoint: new URL(registration.identityRoute ?? DEFAULT_IDENTITY_ROUTE, base).toString(),
     tokenEndpoint: new URL(`${oidcRoute}/token`, base).toString()
   };
@@ -3980,7 +4069,18 @@ var agentAuthRoutes = (config) => {
   if (config === undefined)
     return plugin.as("global");
   if (config.agentRegistration === undefined) {
-    return plugin.get(config.metadataRoute ?? DEFAULT_AGENT_RESOURCE_METADATA_ROUTE, () => agentProtectedResourceMetadata(config)).as("global");
+    plugin.get(config.metadataRoute ?? DEFAULT_AGENT_RESOURCE_METADATA_ROUTE, () => agentProtectedResourceMetadata(config));
+    const { oauthGuide } = config;
+    if (oauthGuide === undefined)
+      return plugin.as("global");
+    const guide = generateAgentOAuthGuide(oauthGuide);
+    plugin.get(agentOAuthGuideRoute(oauthGuide), () => new Response(guide, {
+      headers: {
+        "cache-control": "public, max-age=300",
+        "content-type": "text/markdown; charset=utf-8"
+      }
+    }));
+    return plugin.as("global");
   }
   const registration = config.agentRegistration;
   const identityRoute = registration.identityRoute ?? "/agent/identity";
@@ -26763,7 +26863,7 @@ var createPostgresScimTokenStore = (db) => ({
 });
 // src/agents/registrationClient.ts
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var secureUrl = (value, allowLocalhost) => {
+var secureUrl2 = (value, allowLocalhost) => {
   if (typeof value !== "string")
     return;
   try {
@@ -26853,32 +26953,32 @@ var discoverAgentRegistration = async (resource, options = {}) => {
   const request = options.request ?? fetch;
   const maxBytes = options.maxResponseBytes ?? 256 * 1024;
   const allowLocalhost = options.allowInsecureLocalhost === true;
-  const resourceUrl = secureUrl(resource, allowLocalhost);
+  const resourceUrl = secureUrl2(resource, allowLocalhost);
   if (resourceUrl === undefined)
     throw new Error("Resource URL must use HTTPS");
   const resourceMetadataUrl = new URL("/.well-known/oauth-protected-resource", resourceUrl).toString();
   const prm = await requestJson(request, resourceMetadataUrl, {}, maxBytes);
-  const advertisedResource = secureUrl(prm.body.resource, allowLocalhost);
+  const advertisedResource = secureUrl2(prm.body.resource, allowLocalhost);
   if (advertisedResource === undefined || advertisedResource !== resourceUrl) {
     throw new Error("Protected resource metadata identity mismatch");
   }
-  const authorizationServer = secureUrl(stringArray(prm.body.authorization_servers)[0], allowLocalhost);
+  const authorizationServer = secureUrl2(stringArray(prm.body.authorization_servers)[0], allowLocalhost);
   if (authorizationServer === undefined) {
     throw new Error("No secure authorization server is advertised");
   }
   const asUrl = new URL("/.well-known/oauth-authorization-server", authorizationServer).toString();
   const metadata = await requestJson(request, asUrl, {}, maxBytes);
-  if (secureUrl(metadata.body.issuer, allowLocalhost) !== authorizationServer) {
+  if (secureUrl2(metadata.body.issuer, allowLocalhost) !== authorizationServer) {
     throw new Error("Authorization server issuer mismatch");
   }
-  const tokenEndpoint = secureUrl(metadata.body.token_endpoint, allowLocalhost);
+  const tokenEndpoint = secureUrl2(metadata.body.token_endpoint, allowLocalhost);
   const agentAuth = metadata.body.agent_auth;
   if (tokenEndpoint === undefined || !isObject2(agentAuth)) {
     throw new Error("Authorization server does not advertise agent registration");
   }
-  const identityEndpoint = secureUrl(agentAuth.identity_endpoint, allowLocalhost);
-  const claimEndpoint = secureUrl(agentAuth.claim_endpoint, allowLocalhost);
-  const skill = secureUrl(agentAuth.skill, allowLocalhost);
+  const identityEndpoint = secureUrl2(agentAuth.identity_endpoint, allowLocalhost);
+  const claimEndpoint = secureUrl2(agentAuth.claim_endpoint, allowLocalhost);
+  const skill = secureUrl2(agentAuth.skill, allowLocalhost);
   const assertionMetadata = agentAuth.identity_assertion;
   if (identityEndpoint === undefined || claimEndpoint === undefined || skill === undefined || !isObject2(assertionMetadata)) {
     throw new Error("Agent registration metadata is incomplete");
@@ -27638,7 +27738,7 @@ var createPostgresApiKeyStore = (db) => ({
   }
 });
 // src/oidc/clientIdMetadata.ts
-var secureUrl2 = (value) => {
+var secureUrl3 = (value) => {
   try {
     return new URL(value).protocol === "https:";
   } catch {
@@ -27649,7 +27749,7 @@ var validateClientIdMetadataDocument = (document, expectedClientId) => {
   const errors = [];
   if (document.client_id !== expectedClientId)
     errors.push("client_id does not match the metadata document URL");
-  if (!secureUrl2(document.client_id))
+  if (!secureUrl3(document.client_id))
     errors.push("client_id must use HTTPS");
   if (!Array.isArray(document.redirect_uris) || document.redirect_uris.length === 0)
     errors.push("redirect_uris is required");
@@ -27669,7 +27769,7 @@ var validateClientIdMetadataDocument = (document, expectedClientId) => {
     ["tos_uri", document.tos_uri],
     ["jwks_uri", document.jwks_uri]
   ]) {
-    if (value !== undefined && !secureUrl2(value))
+    if (value !== undefined && !secureUrl3(value))
       errors.push(`${name2} must use HTTPS`);
   }
   return errors;
@@ -27692,7 +27792,7 @@ var createClientIdMetadataResolver = ({
 }) => {
   const cache = new Map;
   return async (clientId) => {
-    if (!secureUrl2(clientId) || !await allow(clientId))
+    if (!secureUrl3(clientId) || !await allow(clientId))
       return;
     const cached = cache.get(clientId);
     if (cached !== undefined && cached.expiresAt > now())
@@ -30371,6 +30471,22 @@ var buildAuthApplications = async (configuration) => {
       tokenTtlMs: registration2.tokenTtlMs
     });
   }
+  if (agentAuth?.oauthGuide !== undefined) {
+    if (oidc === undefined)
+      throw new Error("agentAuth.oauthGuide requires the OIDC provider");
+    if (agentAuth.authorizationServer !== oidc.issuer)
+      throw new Error("agentAuth.authorizationServer must equal oidc.issuer");
+    if (agentAuth.oauthGuide.authorizationServer !== agentAuth.authorizationServer)
+      throw new Error("agentAuth.oauthGuide.authorizationServer must equal agentAuth.authorizationServer");
+    const unknownGuideScopes = agentAuth.oauthGuide.resources.flatMap(({ scopes }) => scopes).filter((scope) => !agentAuth.scopes.includes(scope));
+    if (unknownGuideScopes.length > 0)
+      throw new Error(`Agent OAuth guide uses undeclared scopes: ${[
+        ...new Set(unknownGuideScopes)
+      ].join(", ")}`);
+    if (agentAuth.agentRegistration !== undefined && (agentAuth.agentRegistration.guideRoute ?? "/auth.md") === (agentAuth.oauthGuide.route ?? "/auth.md"))
+      throw new Error("Agent OAuth and registration guides cannot use the same route");
+    generateAgentOAuthGuide(agentAuth.oauthGuide);
+  }
   if (tracing !== undefined)
     await initTracing(tracing);
   const clientProviders = await buildClientProviders(providersConfiguration, createOAuth2Client, customProviders);
@@ -30392,6 +30508,9 @@ var buildAuthApplications = async (configuration) => {
     ...oidc,
     additionalDiscoveryMetadata: {
       ...oidc.additionalDiscoveryMetadata,
+      ...resolvedAgentAuth?.oauthGuide === undefined ? {} : {
+        service_documentation: agentOAuthGuideUrl(resolvedAgentAuth.oauthGuide)
+      },
       ...resolvedAgentAuth?.agentRegistration === undefined ? {} : {
         agent_auth: agentRegistrationDiscoveryMetadata(resolvedAgentAuth)
       }
@@ -30611,5 +30730,5 @@ export {
   auth2 as auth
 };
 
-//# debugId=B037EE5900B85A3664756E2164756E21
+//# debugId=E2F70FC52266FF6C64756E2164756E21
 //# sourceMappingURL=server.js.map