@apitap/core 1.0.17 → 1.0.19

package/src/replay/engine.ts

@@ -6,6 +6,8 @@ import { parseJwtClaims } from '../capture/entropy.js';
 import { refreshTokens } from '../auth/refresh.js';
 import { truncateResponse } from './truncate.js';
 import { resolveAndValidateUrl } from '../skill/ssrf.js';
+import { snapshotSchema } from '../contract/schema.js';
+import { diffSchema, type ContractWarning } from '../contract/diff.js';
 
 // Header security: block dangerous headers from skill files (blocklist approach).
 // All other headers — including custom API headers like Client-ID — pass through.
@@ -66,6 +68,8 @@ export interface ReplayResult {
   refreshed?: boolean;
   /** Whether the response was truncated to fit maxBytes */
   truncated?: boolean;
+  /** Contract warnings from schema drift detection */
+  contractWarnings?: ContractWarning[];
 }
 
 /**
@@ -228,7 +232,9 @@ export async function replayEndpoint(
 
   // Inject auth header from auth manager (if available)
   if (authManager && domain) {
-    const auth = await authManager.retrieve(domain);
+    const auth = endpoint.isolatedAuth
+      ? await authManager.retrieve(domain)
+      : await authManager.retrieveWithFallback(domain);
     if (auth && auth.header && auth.value) {
       headers[auth.header] = auth.value;
     }
@@ -282,15 +288,36 @@ export async function replayEndpoint(
       if (refreshResult.success) {
         refreshed = true;
         // Re-inject fresh auth header
-        const freshAuth = await authManager.retrieve(domain);
+        const freshAuth = endpoint.isolatedAuth
+          ? await authManager.retrieve(domain)
+          : await authManager.retrieveWithFallback(domain);
         if (freshAuth) {
           headers[freshAuth.header] = freshAuth.value;
         }
       }
     } else {
-      // Proactive: check if JWT is expired (30s buffer for clock skew)
-      const currentAuth = await authManager.retrieve(domain);
-      if (currentAuth?.value) {
+      // Proactive expiry check (30s buffer for clock skew)
+      const currentAuth = endpoint.isolatedAuth
+        ? await authManager.retrieve(domain)
+        : await authManager.retrieveWithFallback(domain);
+
+      if (currentAuth?.expiresAt) {
+        // Check 1: expiresAt from OAuth/stored TTL (handles opaque tokens)
+        const expiresAtMs = new Date(currentAuth.expiresAt).getTime();
+        if (expiresAtMs < Date.now() + 30_000) {
+          const refreshResult = await refreshTokens(skill, authManager, { domain, _skipSsrfCheck: options._skipSsrfCheck });
+          if (refreshResult.success) {
+            refreshed = true;
+            const freshAuth = endpoint.isolatedAuth
+              ? await authManager.retrieve(domain)
+              : await authManager.retrieveWithFallback(domain);
+            if (freshAuth) {
+              headers[freshAuth.header] = freshAuth.value;
+            }
+          }
+        }
+      } else if (currentAuth?.value) {
+        // Check 2: JWT exp claim (existing logic)
         const raw = currentAuth.value.startsWith('Bearer ')
           ? currentAuth.value.slice(7)
           : currentAuth.value;
@@ -299,7 +326,9 @@ export async function replayEndpoint(
           const refreshResult = await refreshTokens(skill, authManager, { domain, _skipSsrfCheck: options._skipSsrfCheck });
           if (refreshResult.success) {
             refreshed = true;
-            const freshAuth = await authManager.retrieve(domain);
+            const freshAuth = endpoint.isolatedAuth
+              ? await authManager.retrieve(domain)
+              : await authManager.retrieveWithFallback(domain);
             if (freshAuth) {
               headers[freshAuth.header] = freshAuth.value;
             }
@@ -350,7 +379,9 @@ export async function replayEndpoint(
     if (refreshResult.success) {
       refreshed = true;
       // Re-inject fresh auth
-      const freshAuth = await authManager.retrieve(domain);
+      const freshAuth = endpoint.isolatedAuth
+        ? await authManager.retrieve(domain)
+        : await authManager.retrieveWithFallback(domain);
       if (freshAuth) {
         headers[freshAuth.header] = freshAuth.value;
       }
@@ -441,6 +472,16 @@ export async function replayEndpoint(
     ? wrapAuthError(response.status, data, skill.domain)
     : data;
 
+  // Contract validation: diff response schema against captured baseline
+  let contractWarnings: ContractWarning[] | undefined;
+  if (endpoint.responseSchema && typeof data === 'object' && data !== null) {
+    const actualSchema = snapshotSchema(data);
+    const warnings = diffSchema(endpoint.responseSchema, actualSchema);
+    if (warnings.length > 0) {
+      contractWarnings = warnings;
+    }
+  }
+
   // Apply truncation if maxBytes is set
   if (options.maxBytes) {
     const truncated = truncateResponse(finalData, { maxBytes: options.maxBytes });
@@ -450,10 +491,11 @@ export async function replayEndpoint(
       data: truncated.data,
       ...(refreshed ? { refreshed } : {}),
       ...(truncated.truncated ? { truncated: true } : {}),
+      ...(contractWarnings ? { contractWarnings } : {}),
     };
   }
 
-  return { status: response.status, headers: responseHeaders, data: finalData, ...(refreshed ? { refreshed } : {}) };
+  return { status: response.status, headers: responseHeaders, data: finalData, ...(refreshed ? { refreshed } : {}), ...(contractWarnings ? { contractWarnings } : {}) };
 }
 
 // --- Batch replay ---

package/src/skill/generator.ts

@@ -9,6 +9,7 @@ import { detectRefreshableTokens } from '../capture/token-detector.js';
 import { isLikelyToken } from '../capture/entropy.js';
 import { isOAuthTokenRequest, type OAuthInfo } from '../capture/oauth-detector.js';
 import { diffBodies } from '../capture/body-diff.js';
+import { snapshotSchema } from '../contract/schema.js';
 
 /** Headers to strip (connection control, forwarding, browser-internal, encoding) */
 const STRIP_HEADERS = new Set([
@@ -395,6 +396,12 @@ export class SkillGenerator {
     // Store response bytes on endpoint
     endpoint.responseBytes = exchange.response.body.length;
 
+    // Snapshot response schema for contract validation
+    try {
+      const parsed = JSON.parse(exchange.response.body);
+      endpoint.responseSchema = snapshotSchema(parsed);
+    } catch { /* non-JSON response, skip schema */ }
+
     this.endpoints.set(key, endpoint);
 
     // Store first body for cross-request diffing

package/src/types.ts

@@ -29,6 +29,8 @@ export interface StoredAuth {
   // v0.9: OAuth credentials (stored encrypted, never in skill file)
   refreshToken?: string;
   clientSecret?: string;
+  // v1.1: computed expiry timestamp
+  expiresAt?: string;
 }
 
 /**
@@ -101,6 +103,14 @@ export interface RequestBody {
   refreshableTokens?: string[];  // v0.8: system-refreshed tokens
 }
 
+/** Schema node for contract validation (recursive type tree) */
+export interface SchemaNode {
+  type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
+  fields?: Record<string, SchemaNode>;
+  items?: SchemaNode;
+  nullable?: boolean;
+}
+
 /** A single API endpoint in a skill file */
 export interface SkillEndpoint {
   id: string;
@@ -117,6 +127,8 @@ export interface SkillEndpoint {
   pagination?: PaginationInfo;
   requestBody?: RequestBody;
   responseBytes?: number; // v1.0: response body size in bytes
+  isolatedAuth?: boolean; // v1.1: opt out of cross-subdomain auth fallback
+  responseSchema?: SchemaNode; // v1.1: schema snapshot for contract validation
 }
 
 /** The full skill file written to disk */