@apifuse/provider-sdk 2.2.0-beta.63 → 2.2.0-beta.65

package/dist/provider.d.ts

@@ -11,7 +11,7 @@ export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_
 export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineMode, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
 export { getProviderLocalePath, type ProviderErrorMessageParams, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
-export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, untrustedContent, z, } from "./schema.js";

package/dist/provider.js

@@ -6,7 +6,7 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
-export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
 export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
 export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";

package/dist/runtime/handle.js

@@ -11,7 +11,7 @@
 import { randomInt, randomUUID } from "node:crypto";
 import { isProviderError } from "../errors.js";
 import { HandleError, handleRecoverySentence, isDraftKind, } from "../handle.js";
-import { formatHandleIssuers } from "../handle-meta.js";
+import { formatHandleIssuers, handleHasDirectionalFieldNames } from "../handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, findHandleWordWithinDistance, HIGH_PUBLIC_HANDLE_WORD_COUNT, ISSUABLE_HANDLE_WORDS, PUBLIC_HANDLE_WORD_COUNT, } from "./handle-wordlist.js";
 import { createMemoryProviderRuntimeState } from "./state.js";
 const RECORD_VERSION = 1;
@@ -153,6 +153,14 @@ export function formatNormalizationClasses(classes) {
 // Errors (spec §5)
 // ---------------------------------------------------------------------------
 function publicCollapsedMessage(kind) {
+    // "a new one" is unambiguous only while the kind has one name. When it is
+    // issued under `next_cursor` and accepted under `cursor`, the caller has to
+    // be told which field to read, so use the full recovery sentence — it names
+    // both keys and is identical for invalid / expired / not-found, which is
+    // what keeps the public collapse indistinguishable.
+    if (handleHasDirectionalFieldNames(kind)) {
+        return `\`${kind.fieldName}\` is not valid or has expired. ${handleRecoverySentence(kind)}`;
+    }
     const issuers = formatHandleIssuers(kind.issuedBy);
     const again = issuers ? `Call ${issuers} again to get a new one.` : "Request a new one.";
     return `\`${kind.fieldName}\` is not valid or has expired. ${again}`;

package/dist/runtime/ocr.js

@@ -42,6 +42,10 @@ function createErrorOcrClient(options) {
         });
     };
     return tagCapability({
+        // Own data property: `bindOcrTelemetry` re-spreads the context, so a
+        // getter or prototype member would silently vanish before reaching
+        // provider code.
+        available: false,
         async recognize() {
             return unavailable();
         },
@@ -274,6 +278,7 @@ function toOcrTransportError(error) {
 }
 function createOcrClient(model, recognize) {
     return {
+        available: true,
         recognize,
         async extractCaptchaText(image, options = {}) {
             const result = await recognize({ image, hint: "captcha" });

package/dist/runtime-boundary-lint.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime boundary lint: provider runtime source must reach the outside world
+ * through the SDK context (`ctx.http`, `ctx.stealth`, `ctx.env`,
+ * `ctx.credential`, `ctx.browser`), not through ambient Node/Bun globals.
+ *
+ * Three rules, reported at `error` level: a finding fails `apifuse check` and
+ * `apifuse submit-check` (official and standalone mode alike). The first
+ * release reported them at `warn` as a migration window; the window closed once
+ * the fleet's request-path hits were fixed or acknowledged. A deliberate
+ * exception is acknowledged in code (see below), never through a hidden
+ * allowlist.
+ *
+ * - `process-env-direct-read`: `process.env.X`, `process.env["X"]`, a bare
+ *   `process.env` object use, and the `Bun.env` equivalents. Runtime bootstrap
+ *   keys (`APIFUSE__RUNTIME__*`) are exempt everywhere because `serve()`
+ *   callers read the port and pod identity before a context exists.
+ * - `node-runtime-module-import`: value imports of `fs`, `fs/promises`, `net`,
+ *   `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+ *   the `node:` prefix) via import/export declarations, `require()`, or dynamic
+ *   `import()`, plus the Bun equivalents `Bun.spawn`, `Bun.spawnSync`, `Bun.$`,
+ *   `Bun.file`, `Bun.write`. Type-only imports are not runtime reach and are
+ *   ignored.
+ * - `direct-fetch-call`: a call to the global `fetch` (bare identifier, or
+ *   `globalThis`/`window`/`self`/`global` member). A bare `fetch` call whose
+ *   enclosing scope declares a `fetch` binding (parameter, variable, import,
+ *   function, catch clause) is calling that binding, not the global, and is
+ *   left alone; the check is lexical, so a wrapper that takes `fetch` as a
+ *   parameter does not hide a global `fetch()` elsewhere in the same file.
+ *   `ctx.stealth.fetch()` is a member call and never matches.
+ *
+ * Files are parsed with the script kind their extension implies (`.ts` as
+ * TypeScript, `.tsx` as TSX, …). Parsing everything as TSX would make a
+ * generic arrow (`<T>(value: T) => value`) or an angle-bracket assertion in an
+ * ordinary `.ts` file read as JSX, and everything after it would silently drop
+ * out of the AST.
+ *
+ * Scope is the provider *runtime* source: JavaScript/TypeScript files under
+ * `providerSourceFiles` minus tests, recorded fixtures, the root bootstrap
+ * entrypoints (`dev.ts`, `start.ts`, `deploy.ts`) and the operator tooling
+ * directories (`scripts/`, `tools/`, `bin/`). Tooling legitimately reads the
+ * ambient environment and the filesystem when a human runs it; the rule is
+ * about code the pod executes on behalf of a request.
+ *
+ * A deliberate exception is acknowledged with the same escape hatch the submit
+ * check uses: `// @apifuse-allow <rule>: <reason>` on the finding line or the
+ * line directly above it. Acknowledged findings are reported as information so
+ * `apifuse check` still lists them.
+ */
+import type { LintDiagnostic, ProviderLintInformation, ProviderLintResult } from "./lint.js";
+import { type TypeScriptCompilerModuleLike, type TypeScriptModule } from "./typescript-module.js";
+export declare const PROCESS_ENV_DIRECT_READ_RULE = "process-env-direct-read";
+export declare const NODE_RUNTIME_MODULE_IMPORT_RULE = "node-runtime-module-import";
+export declare const DIRECT_FETCH_CALL_RULE = "direct-fetch-call";
+export declare const RUNTIME_BOUNDARY_RULES: readonly ["process-env-direct-read", "node-runtime-module-import", "direct-fetch-call"];
+export type RuntimeBoundaryRule = (typeof RUNTIME_BOUNDARY_RULES)[number];
+/**
+ * Environment names a provider may read from `process.env` directly. These
+ * are consumed before `serve()` builds a context (port, pod identity), so
+ * `ctx.env` cannot carry them. The whole `APIFUSE__RUNTIME__` family is the
+ * bootstrap contract; nothing else is exempt.
+ */
+export declare const BOOTSTRAP_ENV_NAME_PREFIX = "APIFUSE__RUNTIME__";
+export declare function isBootstrapEnvName(name: string): boolean;
+export declare const TEST_SOURCE_FILE_PATTERN: RegExp;
+type RuntimeBoundaryFinding = {
+    rule: RuntimeBoundaryRule;
+    /** 1-based line. */
+    line: number;
+    /** What was reached: the env name, module specifier, or call text. */
+    subject: string;
+};
+type RuntimeBoundaryFileReport = {
+    findings: RuntimeBoundaryFinding[];
+    acknowledged: Array<RuntimeBoundaryFinding & {
+        reason: string;
+    }>;
+};
+/** True for the files the runtime boundary rules look at. */
+export declare function isRuntimeBoundarySourceFile(relativePath: string): boolean;
+/**
+ * Script kind for a provider source file, from its extension. `.tsx`/`.jsx`
+ * enable JSX; everything else (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`,
+ * and the synthetic names used for in-memory sources) does not, so a generic
+ * arrow or `<T>value` assertion in a `.ts` file parses as TypeScript instead
+ * of swallowing the rest of the file as unterminated JSX.
+ */
+export declare function scriptKindForSourceFile(ts: TypeScriptModule, fileName: string): import("typescript").ScriptKind;
+export declare function analyzeRuntimeBoundary(ts: TypeScriptModule, fileName: string, source: string): RuntimeBoundaryFileReport;
+export type RuntimeBoundaryLintInput = {
+    authFlowSource?: string;
+    providerSourceFiles?: Record<string, string>;
+    operations?: Record<string, {
+        handler?: unknown;
+        source?: string;
+    }>;
+};
+/**
+ * Lint the provider runtime boundary. Returns error-level diagnostics (one per
+ * file and rule, listing every line) and information entries for findings
+ * acknowledged with `@apifuse-allow`.
+ */
+export declare function lintRuntimeBoundary(ts: TypeScriptModule, provider: RuntimeBoundaryLintInput, readOperationSource: (operation: {
+    handler?: unknown;
+    source?: string;
+}) => string): {
+    diagnostics: LintDiagnostic[];
+    information: ProviderLintInformation[];
+};
+export type LintRuntimeBoundarySourcesOptions = {
+    /**
+     * A loaded TypeScript compiler API module to parse with (`typescript` 6.x
+     * or `@typescript/typescript6`). When omitted the SDK resolves one from its
+     * own install location, trying `typescript` first and falling back to
+     * `@typescript/typescript6` when `typescript` is the 7.x native shell
+     * without `createSourceFile`. A caller whose dependency tree pins its own
+     * compiler module (the APIFuse monorepo contract check) passes it here so
+     * the parse does not depend on what hoists next to the SDK.
+     */
+    typescript?: TypeScriptCompilerModuleLike;
+};
+/**
+ * Lint provider runtime source files for the runtime boundary rules without a
+ * provider definition: `files` maps provider-root-relative paths to source
+ * text (the same shape `apifuse check` collects as `providerSourceFiles`).
+ * Out-of-scope paths (tests, recorded fixtures, `.d.ts`, the root
+ * `dev.ts`/`start.ts`/`deploy.ts`, `scripts/`, `tools/`, `bin/`) are skipped
+ * with `isRuntimeBoundarySourceFile`. Diagnostics carry
+ * `field: "sourceFiles.<path>"`; `@apifuse-allow` acknowledgements come back
+ * as `information`.
+ *
+ * Parses with `options.typescript` when given, otherwise with the compiler
+ * module resolved from the installed SDK (see `getTypeScript`). This is the
+ * entry point the platform contract check uses to apply the rules with the
+ * monorepo's SDK pin instead of each provider's own pin.
+ */
+export declare function lintRuntimeBoundarySources(files: Record<string, string>, options?: LintRuntimeBoundarySourcesOptions): ProviderLintResult;
+export {};