@absolutejs/auth 0.56.13 → 0.56.14

package/README.md

@@ -97,6 +97,12 @@ adds a scoped `protectAgent` guard. It can also serve a generated `/auth.md`
 registration guide and matching structured OAuth metadata. This is native to
 `@absolutejs/auth`; no WorkOS service or separate package is required.
 
+Applications using ordinary OAuth dynamic client registration can publish an
+agent-readable `/auth.md` without enabling the separate claim/ID-JAG profile.
+Set `agentAuth.oauthGuide` to the exact enabled protected resources, metadata
+URLs, and scopes. Auth serves the guide and advertises it through RFC 8414
+`service_documentation`; the structured OAuth metadata remains authoritative.
+
 Protocol-specific credentials are normalized by verifier adapters:
 
 ```ts

package/dist/agents/config.d.ts

@@ -1,6 +1,7 @@
 import type { RouteString } from '../types';
 import type { AgentCredentialVerifier, AgentDelegationStore, AgentRegistrationStore } from './types';
 import type { AgentRegistrationProtocolConfig } from './registration';
+import type { AgentOAuthGuideConfig } from './oauthGuide';
 export declare const DEFAULT_AGENT_RESOURCE_METADATA_ROUTE: RouteString;
 export type AgentRegistrationDiscoveryMetadata = {
     claim_endpoint: string;
@@ -18,6 +19,10 @@ export type AgentAuthConfig = {
     /** Open auth.md agent-registration support. Implemented natively by Absolute
      * Auth and projected through OAuth discovery; no WorkOS service is required. */
     agentRegistration?: AgentRegistrationProtocolConfig;
+    /** Agent-readable OAuth onboarding derived from the same protected resources
+     * and scopes the application actually enables. This is separate from the
+     * optional claim/ID-JAG registration profile. */
+    oauthGuide?: AgentOAuthGuideConfig;
     authorizationServer: string;
     delegationStore: AgentDelegationStore;
     logoUri?: string;

package/dist/agents/index.d.ts

@@ -3,6 +3,7 @@ export * from './types';
 export * from './registration';
 export * from './registrationClient';
 export * from './idJag';
+export * from './oauthGuide';
 export * from '../oidc/clientIdMetadata';
 export { createOidcAgentCredentialVerifier } from './oidcAdapter';
 export { agentHasScopes, resolveAgentPrincipal } from './principal';

package/dist/agents/index.js

@@ -1165,8 +1165,96 @@ var createAgentIdentityAssertionVerifier = ({
     subject
   };
 };
+// src/agents/oauthGuide.ts
+var DEFAULT_GUIDE_ROUTE2 = "/auth.md";
+var secureUrl2 = (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_ROUTE2;
+var agentOAuthGuideUrl = (config) => new URL(agentOAuthGuideRoute(config), secureUrl2(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: secureUrl2(resource.metadataUrl, "Protected-resource metadata URL"),
+    name: resource.name.trim(),
+    resource: secureUrl2(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 = secureUrl2(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/oidc/clientIdMetadata.ts
-var secureUrl2 = (value) => {
+var secureUrl3 = (value) => {
   try {
     return new URL(value).protocol === "https:";
   } catch {
@@ -1177,7 +1265,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");
@@ -1197,7 +1285,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(`${name} must use HTTPS`);
   }
   return errors;
@@ -1220,7 +1308,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())
@@ -1626,7 +1714,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";
@@ -13585,6 +13684,7 @@ export {
   issueAgentIdentityAssertion,
   handleAgentTokenGrant,
   generateAgentRegistrationGuide,
+  generateAgentOAuthGuide,
   discoverAgentRegistration,
   createPostgresAgentRegistrationStore,
   createPostgresAgentIdentityRegistrationStore,
@@ -13608,6 +13708,8 @@ export {
   agentRegistrationEndpoints,
   agentRegistrationDiscoveryMetadata,
   agentProtectedResourceMetadata,
+  agentOAuthGuideUrl,
+  agentOAuthGuideRoute,
   agentIdentityRegistrationsTable,
   agentHasScopes,
   agentDelegationsTable,
@@ -13620,5 +13722,5 @@ export {
   AGENT_CLAIM_GRANT_TYPE
 };
 
-//# debugId=3257C9C351E3F2FA64756E2164756E21
+//# debugId=DE3C9B11A35558B764756E2164756E21
 //# sourceMappingURL=index.js.map