@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/CHANGELOG.md

@@ -1,5 +1,263 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.70
+
+- Release candidate for main commit 429f8f7658812835aa4ca1465ef682c2934dfe3e.
+
+## 2.2.0-beta.69
+
+- Release candidate for main commit 0f4bd33ef5bd41cb6813005e923abf4324158582.
+
+## 2.2.0-beta.68
+
+- Release candidate for main commit d630a344c18b2b192edfd09ef92bc30a482b6b8d.
+
+## 2.2.0-beta.67
+
+- Release candidate for main commit 9ef92b86b293253597801e29764d76beb0a3f3b7.
+
+## 2.2.0-beta.66
+
+- Release candidate for main commit e7f93a6c71e3bca3a680861c0968e22dbe5d1d40.
+
+## 2.2.0-beta.65
+
+- Release candidate for main commit 4731ac76145caf85a6c340ad0c446371bd24b052.
+
+## 2.2.0-beta.64
+
+- Release candidate for main commit 0505a938340d08db3ea3e2302cab5f6b5dd2b4e5.
+
+## 2.2.0-beta.63
+
+- Release candidate for main commit a9b85acc5af4c40ec59774b0d1e864e7ed21828e.
+
+## 2.2.0-beta.62
+
+- Release candidate for main commit 98c623f799268b6d13ce59844b2b33ed78dcd0c3.
+
+## 2.2.0-beta.61
+
+- Release candidate for main commit 8ba435285f6f448bb1b8d01b1d65d2e1a4b42aaa.
+
+## 2.2.0-beta.60
+
+- Release candidate for main commit 5f417c6282b3a4d92bf31c8258ba913b5e53dc8b.
+
+## 2.2.0-beta.59
+
+- Release candidate for main commit 55ae556fcf33e28a228c2d54ce76e7afa41e5dc7.
+
+## 2.2.0-beta.58
+
+- Release candidate for main commit e137940caa8bc32ce768571a6197651e581c2270.
+
+## 2.2.0-beta.57
+
+- Release candidate for main commit 4087dafdeab771eb91691884ce7315b8c399f863.
+
+## 2.2.0-beta.56
+
+- Release candidate for main commit 390167b3f51488be0beba25a1ea5eb425d3bf839.
+
+## 2.2.0-beta.55
+
+- Release candidate for main commit 1c495af089940a4c666e6baf58dc0dd577771a40.
+
+## 2.2.0-beta.54
+
+- Release candidate for main commit 4dccd0cd9d3443cde4edebf98ffc6c11beecb9ea.
+
+## 2.2.0-beta.53
+
+- Release candidate for main commit 40a916bac16bb2b2bbda7fc4a96132d10ca103bf.
+
+## 2.2.0-beta.52
+
+- Release candidate for main commit 6e64ae0ad2e735b3de0c115f5ea29517efcf4ff2.
+
+## 2.2.0-beta.51
+
+- Release candidate for main commit a1269b0a7161618e5fc25e532aaa45de0efd632f.
+
+## 2.2.0-beta.50
+
+- Release candidate for main commit 341c2f0e55a4159cac423fec0bf4f84625191731.
+
+## 2.2.0-beta.49
+
+- Release candidate for main commit 694b145f65c2c81e298c2516dde221ce19cb52da.
+
+## 2.2.0-beta.48
+
+- Release candidate for main commit ba6636fa8dd53a35af3091ae6efd797f5ef3d836.
+
+## 2.2.0-beta.47
+
+- Release candidate for main commit 0ff0c6c90153af3aab75978eb73040c9adaa2609.
+
+## 2.2.0-beta.46
+
+- Release candidate for main commit 0340fbc51b4ad71689bb1ec61b9b818dedda4587.
+
+## 2.2.0-beta.45
+
+- Release candidate for main commit 5d337d9fc1c77cd814ec7a4e1aa44ba0f8b2a5a9.
+
+## 2.2.0-beta.44
+
+- Release candidate for main commit a3091c0b4931c5ae48fe01b9776e4dc213db2716.
+
+## 2.2.0-beta.43
+
+- Release candidate for main commit 5b8b6048514fb500ead400495bd5e1ed8695ed6d.
+
+## 2.2.0-beta.42
+
+- Release candidate for main commit efbdbb409c9400e6211b061705b634e659f298bd.
+
+## 2.2.0-beta.41
+
+- Release candidate for main commit e1bde60e6a9e0424074a357afd9e8af56549080d.
+
+## 2.2.0-beta.40
+
+- Release candidate for main commit 7e2f05a954c23593a77e89e463a9bcbc2cdc7695.
+
+## 2.2.0-beta.39
+
+- Release candidate for main commit ecbe349c44e15c873b7c58b42e14610db029eb5f.
+
+## 2.2.0-beta.38
+
+- Release candidate for main commit 448775077dbc9ab907209f1feee4e6e4e5ef4283.
+
+## 2.2.0-beta.37
+
+- Release candidate for main commit aa14b268dffe1196f25c2b6b314598fe0896edec.
+
+## 2.2.0-beta.36
+
+- Release candidate for main commit c6858f8b87d78b3b755adeb28982e875434be406.
+
+## 2.2.0-beta.35
+
+- Release candidate for main commit 027fa0087b883a6281bc6d8bdaaf6d0be382000f.
+
+## 2.2.0-beta.34
+
+- Release candidate for main commit 383a97e7d0ce995d098d5f95c9ffdcbeed13de31.
+
+## 2.2.0-beta.33
+
+- Release candidate for main commit e7d854ec3e859702b22e2b37eaa2ae6bd4545c80.
+
+## 2.2.0-beta.32
+
+- Release candidate for main commit 82f1c0c1de916a40c8c74b1d6470a493b134c0ed.
+
+## 2.2.0-beta.31
+
+- Release candidate for main commit 94006be0852918867d254dc23d0fa8420a07be9c.
+
+## 2.2.0-beta.30
+
+- Release candidate for main commit ccf3d56bfcbe9683c6e7ad45dde8e6703467f9e7.
+
+## 2.2.0-beta.29
+
+- Release candidate for main commit b7243459ab12403e11d7b5b93292f09b734b0a96.
+
+## 2.2.0-beta.28
+
+- Release candidate for main commit 2936f1891d4e2326502f0585081f8a58060d6dd7.
+
+## 2.2.0-beta.27
+
+- Release candidate for main commit 579d9e7fd22d8414b151be2b71a43a0990456911.
+
+## 2.2.0-beta.26
+
+- Release candidate for main commit 924fe13d1101e7840d799a562a7a70174355185d.
+
+## 2.2.0-beta.25
+
+- Release candidate for main commit e6df658b95c0728b671fd221919ec2f85f82b0b7.
+
+## 2.2.0-beta.24
+
+- Release candidate for main commit 0f21a2959dcbb9b96fe426259259d0870cfc537f.
+
+## 2.2.0-beta.23
+
+- Release candidate for main commit 36b3bedc9c14913c4152c4631cc87de71062f21f.
+
+## 2.2.0-beta.22
+
+- Release candidate for main commit b8bf920b5ca053d1bf43018167fd4eedff01700d.
+
+## Unreleased
+
+- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed.
+- **Breaking:** Legacy encrypted server-handle choice tokens are no longer parsed. They are rejected with the uniform choice-not-found error; server-stored choices are now word-only. Encrypted inline choice tokens remain supported.
+- Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
+
+## 2.2.0-beta.21
+
+- Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.
+
+## 2.2.0-beta.20
+
+- Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
+
+## 2.2.0-beta.19
+
+- Release candidate for main commit fd93ae68d0472fae68d908312249163373ec5d22.
+
+## 2.2.0-beta.18
+
+- Release candidate for main commit cebaf4b994918d2641c0fe6681fbffd3a3284c5d.
+
+## 2.2.0-beta.17
+
+- Release candidate for main commit 5a0f9127a5861992d5c144b07ad379a085756544.
+
+## 2.2.0-beta.16
+
+- Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
+
+## 2.2.0-beta.15
+
+- Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
+
+## 2.2.0-beta.14
+
+- Release candidate for main commit 3491acd253ca17b517985e8a618f1c2904a664a9.
+
+## 2.2.0-beta.13
+
+- Release candidate for main commit 75e840d0614aea3b99a1e5cef4f93f8cdccf0507.
+
+## 2.2.0-beta.12
+
+- Release candidate for main commit c66789c4745c72fc94ad3c10b3e0d7e5ed83fd25.
+
+## 2.2.0-beta.11
+
+- Release candidate for main commit f6f739bd5265afe714bbace9900edc2695fcf826.
+
+## 2.2.0-beta.10
+
+- Release candidate for main commit c41bd919739e0293ae8fa4d72a8a32f034cef4b8.
+
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
 ## 2.2.0-beta.7
 
 - Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.
@@ -58,8 +316,22 @@
 
 ## Unreleased
 
+- Upstream the platform monorepo's beta.16 dist patch: OAuth2-proxied auth ceremony (`createOAuth2ProxiedStart`, `OAUTH2_PROXIED_PKCE_VERIFIER_KEY`, `APIFUSE__AUTH_PROXY__URL` origin key, proxied redirect/callback turns) and the provider runtime state upgrades it depends on (in-memory compareAndSet with quota-aware write policy, Redis CAS/set Lua scripts with entry quotas and legacy index migration). The monorepo drops `patchedDependencies` once it pins this release.
+- **honest-provider-error-contract (phase 2):** `UPSTREAM_REJECTED` is a registered code family serving HTTP 409 with `retryable: false` — deterministic upstream business refusals are no longer 502s. Operation-declared `docs.errorCodes` may now use 409/410/422. Public error envelopes carry a `source` field (`client` | `upstream_rule` | `upstream_failure` | `apifuse`) derived from the observability category. Taxonomy version bumps to `2026-08-07` with the `upstream_rejected`, `dependency_unavailable`, `unsupported_transport`, and `client_cancelled` categories (409/410/422 map to `upstream_rejected`), matching the platform monorepo SoT. The `unregistered_provider_error_code` signal now carries a `signalFix` pointing at `docs.errorCodes` declaration.
+- **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
+- Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
+- Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
+- Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
+- **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.
+- Unregistered `ProviderError` codes now default to HTTP 500 instead of 400 and emit an `unregistered_provider_error_code` structured-log signal; registered mappings remain unchanged and take precedence over the HTTP 400 fallback for unregistered input `ValidationError` codes.
+- Add an opt-in native connection idle read timeout with a typed error, independently from TCP/SOCKS/TLS establishment deadlines.
+- Add opt-in `maxBodyBytes` enforcement to stealth fetches and redirect hops, aborting oversized decoded response streams with `response_too_large`.
+- Resolve relative date tokens in fixture requests before input-schema validation, add KST capture-date `fixtures.recordedAt` metadata, and support explicit KST/UTC calendars in the shared health-input resolver.
+- Add opt-in `runStandardTests(provider, { upstreamStub })` real-handler E2E coverage with strict offline transport stubs, output-schema validation, and per-operation warnings when handler E2E is not enabled.
+- Export native-network and request-file TypeScript contracts from the package root and `./provider`, including typed native provider declarations and optional runtime capabilities on provider/auth contexts.
 - Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
 - Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
+- Accept and validate `proxy.session.drainLeadSeconds` in `defineProvider`, so providers can actually declare the native sticky-expiry drain lead time the type surface already exposed; a non-positive value, or one that meets or exceeds the sticky lifetime, is rejected at define time.
 
 ## 2.1.0-beta.15
 
@@ -115,7 +387,7 @@
 
 ## 2.1.0-beta.3
 
-- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by `impit` browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
+- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
 - Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
 - Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
 - Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vooy Korea, Inc. (주식회사 부이코리아)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -40,6 +40,8 @@ Do not use internal monorepo placement for bounty workspaces. Accepted provider
 - Dev default: `3900`
 - Start/Docker/container contract: `3000`
 - `GET /health`
+- `GET /readyz`
+- `GET /__apifuse/diagnostics/runtime` (internal runtime diagnostics, see `AUTHORING.md`)
 - `POST /v1/{operation}`
 - `POST /auth/start`
 - `POST /auth/continue`
@@ -76,7 +78,15 @@ The operation request body is the same envelope used by the APIFuse gateway:
 | `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
 | `input` | yes | The operation input after schema validation. |
 | `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
-| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+| `connectionId` | no | Connection identity only; it does not include credentials. The gateway sends it for `optional` connection mode, and only when the caller supplied a connection that passed authorization. Exposed as `ctx.request.connectionId`. |
+| `connection` | no | Credential-bearing connection data. The gateway sends it for `required` connection mode; omit it for no-auth/public (`none` mode) operations. For local debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+| `tenantId` | no | Gateway-asserted principal scope: the organization id for customer subjects, the service-account id for platform service accounts. Sent for every connection mode, including `none`; absent on direct calls and self-test. Exposed as `ctx.request.tenantId` (`undefined` when absent or empty). Caller headers never populate it. |
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Credential-bearing local smoke example:
 
@@ -115,9 +125,10 @@ the bad request path; provider/runtime failures include `code`, `message`, and
 - **`invalid_request` on `/v1/{operation}`**: confirm the request body includes
   `requestId` and `input`. Omit `connection` for public/no-auth operations;
   never send `connection: null`.
-- **Credential-backed operations**: declare `credential.keys`, then pass matching
-  local-only values through `connection.secrets`. Read them in handlers with
-  `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
+- **Credential-backed operations**: declare `credential.keys`, except when
+  `auth.mode` is `platform-managed`; that auth declaration implies an unfiltered
+  credential capability. Pass local-only values through `connection.secrets` and
+  read them with `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
   `.env`, and read only those names through `ctx.env.get("NAME")`. The SDK
   enforces presence of `required: true` declarations before handlers and auth
@@ -137,15 +148,70 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
-  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
-  accepts request controls for `params`, `proxy`, `timeout`, `profile`,
-  `redirect`, `throwOnHttpError`, and `stealth.insecureSkipVerify`. For login
+  `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
+  accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`,
+  `maxBodyBytes`, `redirect`, `redirectPolicy`, `throwOnHttpError`, and
+  `stealth.insecureSkipVerify`. A followed redirect drops `Authorization` when
+  it leaves the origin and an explicit `Cookie` when it leaves the site (the
+  session cookie jar takes over there); set
+  `redirectPolicy: { mode: "same-origin", maxHops }` to refuse a cross-origin
+  hop with `HttpRedirectError` before any request reaches it. For login
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
-  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
-  pseudo-header order in provider code. Chrome/Firefox-style profiles are
-  supported; use `ctx.browser` when Safari-specific behavior is required.
+  identity with structured `stealth: { browser, os }` options; omitted `os`
+  explicitly defaults to `macos`. The transport owns `User-Agent`,
+  `Accept-Encoding`, `sec-ch-ua*`, and every `Sec-Fetch-*` header and throws
+  `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` if you set one; declare
+  `stealth.requestClass: "navigation" | "form-post" | "xhr" | "post"` instead
+  (`form-post` for an HTML form submission). The offline
+  `ctx.stealth` in `runStandardTests` runs the same check, so a provider test
+  fails wherever production would. Do not pin a
+  browser version
+  or tune JA3, HTTP/2 SETTINGS, or
+  pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
+  are supported; use `ctx.browser` when the provider needs browser execution.
+- **Query-parameter credentials**: when an upstream requires a credential in
+  its URL query, pass it through `sensitiveParams`, not `params` and never a
+  hand-built URL. It is sent as a normal query parameter while the SDK redacts
+  its value from transport errors, traces, and recorded fixtures:
+
+  ```ts
+  const response = await ctx.http.get("/openapi/service", {
+    params: { page: 1 },
+    sensitiveParams: { serviceKey: ctx.env.get("APIFUSE__PROVIDER__EXAMPLE__API_KEY")! },
+  });
+  ```
+
+  Use this only when the upstream offers no header or body credential channel.
+  Declared query-key positions and exact scalar diagnostics are always redacted.
+  Free-text values of four or more characters are redacted as substrings; shorter
+  values require token boundaries so low-entropy values do not corrupt unrelated
+  words or timestamps. Consequently, a sub-four-character secret embedded in a
+  larger alphanumeric token can remain in free text; prefer higher-entropy or
+  non-query credentials when possible. `sensitiveParams: {}` is equivalent to
+  omitting the option. Redirect results structurally redact declared keys and
+  common response-only credential keys from hop URLs; use
+  `redirects.run({ stopWhen })` to inspect a real intermediate `Location` during
+  the run when a login flow needs a rotated value.
+- **Proxy URLs for non-stealth consumers**: use `resolveProxy()` when a
+  provider-owned client outside `ctx.stealth` needs the provider's proxy, such
+  as a CAPTCHA solver that must use matching egress. Pass the provider proxy
+  policy used by the provider and consume the returned `url`; the SDK owns
+  vendor selection, allocation, failover, and URL formats. Never call proxy
+  allocator APIs or hardcode proxy vendor hostnames in provider code.
+
+  ```ts
+  import { resolveProxy } from "@apifuse/provider-sdk"
+
+  const resolvedProxy = await resolveProxy({
+    proxyPolicy,
+    affinityKey: connectionId,
+  })
+
+  if (!resolvedProxy.url) throw new Error("This login requires proxy egress")
+  const captchaTask = { proxy: resolvedProxy.url }
+  ```
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when
@@ -154,12 +220,29 @@ the bad request path; provider/runtime failures include `code`, `message`, and
 
 ## Authoring ergonomics
 
-`defineProvider()` infers each operation handler input from the operation `input` schema. For larger providers, factor operations with `defineOperation()` and compose them later:
+`defineProvider()` establishes the capability declaration before its returned
+builder contextually types operations. For larger providers, export the derived
+context once and use it with `defineOperation()` in separate files:
 
 ```ts
-import { defineOperation, defineProvider, z } from "@apifuse/provider-sdk/provider"
+import {
+  defineOperation,
+  defineProvider,
+  type ProviderContextOf,
+  z,
+} from "@apifuse/provider-sdk/provider"
+
+const buildProvider = defineProvider({
+  id: "factored-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  meta: { displayName: "Factored", category: "demo" },
+})
 
-const search = defineOperation({
+export type ProviderContext = ProviderContextOf<typeof buildProvider>
+
+const search = defineOperation<ProviderContext>()({
+  riskClass: "read",
   input: z.object({ q: z.string().describe("Search query") }),
   output: z.object({ count: z.number().describe("Result count") }),
   async handler(ctx, input) {
@@ -170,11 +253,7 @@ const search = defineOperation({
   },
 })
 
-export default defineProvider({
-  id: "factored-provider",
-  version: "1.0.0",
-  runtime: "standard",
-  meta: { displayName: "Factored", category: "demo" },
+export default buildProvider({
   operations: { search },
 })
 ```
@@ -211,17 +290,17 @@ healthCheck: {
 }
 ```
 
-### Operation annotations
+### Flat operation metadata
 
-Operations declare non-functional metadata via `annotations`:
+Operations declare access, safety, and execution metadata directly on the
+operation. `riskClass` is required and is the safety source of truth:
 
 | Field | Type | Notes |
 |---|---|---|
-| `readOnly` | `boolean` | Operation has no side effects (safe to test in production). |
-| `destructive` | `boolean` | Operation modifies/deletes state. |
-| `idempotent` | `boolean` | Safe to retry without duplicate side effects. |
-| `openWorld` | `boolean` | Callable without authentication. |
-| `rateLimit` | `{ calls, window }` | Per-operation rate hint. `window` is `"minute"\|"hour"\|"day"`. |
+| `riskClass` | `"read" \| "write" \| "destructive" \| "external-send"` | Required safety classification. |
+| `approval` | `"never" \| "risk-based" \| "always"` | Optional override; omit when it matches the risk-class default. |
+| `connectionMode` | `"none" \| "optional" \| "required"` | Access requirement. Required by lint for credential-bearing providers. |
+| `connectionExternalRefParam` | `string` | Public argument used to resolve a Connection. |
 | `timeoutMs` | `number` | Per-operation upstream timeout (1–60000 ms). Omit to inherit the gateway global default. |
 
 `defineProvider()` validates `timeoutMs` is an integer in `[1, 60000]` and throws `ValidationError` otherwise. The gateway applies the value via `context.WithTimeout` on every proxied call and clamps defensively to the same bound.
@@ -239,10 +318,14 @@ apifuse bounty-check [path]
 apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 ```
 
-`apifuse record` is for real upstream-backed operations that declare
-`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.stealth`. The
-generated local-only `ping` operation intentionally has no upstream and should
-be replaced before recording fixtures.
+`apifuse record` is for real upstream-backed operations that call the upstream
+through `ctx.http` or `ctx.stealth`. Absolute request URLs need no declaration; a
+relative URL resolves the way `serve` resolves it — against the operation's
+`upstream.baseUrl`, else the provider's first declared one (`ctx.stealth` then
+falls back to `https://<allowedHosts[0]>`). A relative `ctx.http` URL with no base
+is refused with the `upstream.baseUrl` to declare. The generated local-only `ping`
+operation intentionally has no upstream and should be replaced before recording
+fixtures.
 
 ## Bounty submission readiness
 
@@ -267,3 +350,8 @@ External bounty contributors should submit standalone Provider source plus
 `bun run check` / `bun run test` evidence. APIFuse maintainers own monorepo
 import, registry generation, deployment projection checks, and release
 publishing.
+
+Relayed user-generated text (listing bodies, reviews, posts) is contained by the
+platform, not by the provider. Wrap such output fields in `untrustedContent(...)`
+so the schema carries `x-apifuse-content-trust: untrusted` and
+`x-apifuse-content-provenance: external`; do not strip instruction-like prose.

package/SUBMISSION.md

@@ -28,7 +28,7 @@ The score is a triage aid, not a payout guarantee. Maintainers still review corr
 | Category | Points | Examples |
 |---|---:|---|
 | Definition & metadata | 15 | `defineProvider`, package, Dockerfile, SDK structural checks |
-| Operations & schemas | 15 | strong descriptions, annotations, input/output schemas |
+| Operations & schemas | 15 | locale-keyed descriptions, explicit risk classes, input/output schemas |
 | Fixtures & tests | 15 | bidirectional fixtures that parse against schemas |
 | Health coverage | 15 | real `healthCheck` or specific `healthCheckUnsupported.reason` |
 | Runtime/local smoke | 10 | `/health` and at least one `POST /v1/{operation}` note |
@@ -46,7 +46,8 @@ Fix all blockers before submitting:
 - Missing fixture request or response.
 - Fixture data does not parse against schemas.
 - Missing `healthCheck` or `healthCheckUnsupported` on any Operation.
-- Credential-backed auth mode without declared credential keys.
+- User-managed credential auth mode without declared credential keys
+  (`platform-managed` auth instead implies the credential capability and forbids keys).
 - High-confidence secret or token material in source, README, package metadata, or fixtures.
 - SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.