@voxgig/apidef 8.0.3 → 8.2.0

package/src/transform/top.ts

@@ -3,7 +3,9 @@ import { join } from '@voxgig/struct'
 
 import { KIT } from '../types'
 
-import { firstSentence } from '../utility'
+import {
+  firstSentence, authExchangeOp, specSecuredByDefault, sortedEntries,
+} from '../utility'
 
 import type { TransformResult } from '../transform'
 
@@ -95,6 +97,17 @@ const topTransform = async function(
     const security = resolveSecurity(def)
     if (null != security) {
       kit.info.security = security
+
+      // Record the ACCESS-TOKEN EXCHANGE, when the spec describes one. The
+      // endpoint that issues credentials is not a resource and does not
+      // become an entity (the guide deactivates it — see
+      // guide/heuristic01.ts and ADR-002); these facts are how it survives
+      // into the model instead, and they are exactly what sdkgen's
+      // `secrets` feature needs to drive the exchange.
+      const exchange = findAuthExchange(def)
+      if (null != exchange) {
+        kit.info.security.exchange = exchange
+      }
     }
   }
 
@@ -361,6 +374,50 @@ function resolveSecurity(def: any): Record<string, string> | null {
 }
 
 
+// Find the spec's access-token exchange and describe it as model facts:
+// where it lives, and the field names it sends and answers with. Returns
+// null when the spec describes no exchange, which is the common case.
+//
+// `path` is RELATIVE to the server URL, with no leading slash, because the
+// server URL already carries whatever account or tenant segment the API
+// templates into it — an absolute path would drop that segment. sdkgen's
+// secrets feature resolves it against `options.base` for the same reason.
+//
+// Only the FIRST exchange is recorded. A spec describing two token
+// endpoints is describing two auth schemes, which is a bigger thing than a
+// field on info.security and is not guessed at here.
+function findAuthExchange(def: any): Record<string, string> | null {
+  const secured = specSecuredByDefault(def)
+  if (!secured) {
+    return null
+  }
+
+  for (const [pathStr, pdef] of sortedEntries(def.paths ?? {})) {
+    for (const [methodName, mdef] of sortedEntries(pdef as any)) {
+      const found = authExchangeOp(
+        { ...(mdef as any), method: methodName.toUpperCase() }, secured)
+
+      if (null != found) {
+        const out: Record<string, string> = {
+          path: String(pathStr).replace(/^\/+/, ''),
+          method: methodName.toUpperCase(),
+          response: found.response,
+        }
+        // Only when the heuristic actually recognised the credential field.
+        // Absent, sdkgen keeps its own documented default rather than
+        // carrying a guess that reads like a fact.
+        if (null != found.request) {
+          out.request = found.request
+        }
+        return out
+      }
+    }
+  }
+
+  return null
+}
+
+
 // Extract the credential prefix from a securityScheme's / info prose.
 // Three signals, in confidence order:
 //   1. An explicit `Authorization: <prefix> <cred>` line (any prefix word)

package/src/types.ts

@@ -255,6 +255,13 @@ type GuideMetrics = {
 type GuideEntity = {
   name: string
   orig: string
+  // `false` drops the entity downstream (transform/entity.ts). Emitted by
+  // the heuristic for an access-token exchange, and editable in guide.aon —
+  // which is the ONLY correction surface (ADR-002).
+  active?: boolean
+  // Why the heuristic deactivated it, so guide.aon reads as a record of a
+  // decision rather than an unexplained `active: false`.
+  why_inactive?: string
   // GraphQL guides key operations by schema root field instead of path;
   // the two branches are mutually exclusive per guide.
   field?: Record<string, GuidePath>

package/src/utility.ts

@@ -1243,6 +1243,131 @@ function guideActive(node: any): boolean {
 }
 
 
+// An API's ACCESS-TOKEN EXCHANGE is not a resource, and must not become an
+// entity. The shape apidef looks for is the one every such endpoint has:
+//
+//   1. The spec as a whole is SECURED (a top-level `security` requirement).
+//      Without that, a per-operation `security: []` clears nothing and
+//      carries no signal at all.
+//   2. The operation clears that requirement with its own `security: []` —
+//      it is the one call a client can make before it holds a credential,
+//      because it is what issues them.
+//   3. It is a POST. A credential exchange writes; a GET that happens to
+//      return a field called `token` is far likelier to be a resource.
+//   4. Its success response carries a TOKEN-shaped field.
+//
+// All four together, or it is a resource. There is deliberately no vendor
+// extension and no overlay to say otherwise (ADR-002): a spec apidef does
+// not control cannot be annotated anyway, and a heuristic that can be
+// corrected in guide.aon needs no second correction surface.
+//
+// Returns the field names the exchange uses, which is what sdkgen's
+// `secrets` feature needs to drive it, or null when this is a resource.
+const AUTH_TOKEN_FIELDS = [
+  'access_token', 'accessToken', 'access-token',
+  'id_token', 'idToken',
+  'token', 'jwt',
+]
+
+// What the exchange SENDS. Optional: an operation answering with an access
+// token is an exchange whether or not apidef recognises the credential it
+// was bought with, and sdkgen carries its own default for the field name.
+const AUTH_CREDENTIAL_FIELDS = [
+  'refresh_token', 'refreshToken', 'refresh-token',
+  'client_secret', 'clientSecret',
+  'assertion', 'grant_type', 'grantType',
+  'api_key', 'apiKey', 'apikey',
+  'password', 'code',
+]
+
+function authExchangeOp(
+  op: any,
+  specSecured: boolean
+): { request: string | null, response: string } | null {
+  if (true !== specSecured) {
+    return null
+  }
+
+  // An empty ARRAY, specifically. `security` absent means "inherit the
+  // global requirement"; `security: []` means "no credential needed here".
+  if (!Array.isArray(op?.security) || 0 !== op.security.length) {
+    return null
+  }
+
+  if ('POST' !== String(op?.method ?? '').toUpperCase()) {
+    return null
+  }
+
+  const response = firstFieldMatch(
+    schemaProps(successResponseSchema(op?.responses)), AUTH_TOKEN_FIELDS)
+
+  if (null == response) {
+    return null
+  }
+
+  const request = firstFieldMatch(
+    schemaProps(requestBodySchema(op?.requestBody)), AUTH_CREDENTIAL_FIELDS)
+
+  return { request, response }
+}
+
+
+// Does the spec require a credential by default? Only a non-empty top-level
+// `security` makes a per-operation `security: []` meaningful.
+function specSecuredByDefault(def: any): boolean {
+  return Array.isArray(def?.security) && 0 < def.security.length
+}
+
+
+// The 2xx body schema, OpenAPI 3 (`content`) or Swagger 2 (`schema`).
+function successResponseSchema(responses: any): any {
+  const res = responses?.['200'] ?? responses?.[200] ??
+    responses?.['201'] ?? responses?.[201]
+  if (null == res) {
+    return null
+  }
+  return res.content?.['application/json']?.schema ?? res.schema ?? null
+}
+
+
+function requestBodySchema(requestBody: any): any {
+  if (null == requestBody) {
+    return null
+  }
+  return requestBody.content?.['application/json']?.schema ?? null
+}
+
+
+function schemaProps(schema: any): string[] {
+  const props = schema?.properties
+  if (null == props || 'object' !== typeof props) {
+    return []
+  }
+  return Object.keys(props)
+}
+
+
+// First name in `names` that the schema declares, compared case-insensitively
+// so `Access_Token` matches `access_token`. Ordered by the CANDIDATE list, not
+// by declaration order, so `access_token` wins over a sibling `token`.
+function firstFieldMatch(props: string[], names: string[]): string | null {
+  const lower = new Map<string, string>()
+  for (const p of props) {
+    const k = p.toLowerCase()
+    if (!lower.has(k)) {
+      lower.set(k, p)
+    }
+  }
+  for (const name of names) {
+    const hit = lower.get(name.toLowerCase())
+    if (null != hit) {
+      return hit
+    }
+  }
+  return null
+}
+
+
 function cleanComponentName(
   name: string,
   isKnownCmp?: (canonizedRemainder: string) => boolean
@@ -1826,6 +1951,8 @@ export {
   transliterate,
   cleanComponentName,
   guideActive,
+  authExchangeOp,
+  specSecuredByDefault,
   ensureMinEntityName,
   inferFieldType,
   normalizeFieldName,