npm - @webpieces/core-util - Versions diffs - 0.4.763 → 0.4.766 - Mend

@webpieces/core-util 0.4.763 → 0.4.766

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/package.json +1 -1
package/src/http/decorators.d.ts +2 -0
package/src/http/decorators.js +2 -0
package/src/http/decorators.js.map +1 -1
package/src/index.d.ts +4 -0
package/src/index.js +16 -2
package/src/index.js.map +1 -1
package/src/mcp/DtoSchema.d.ts +70 -0
package/src/mcp/DtoSchema.js +294 -0
package/src/mcp/DtoSchema.js.map +1 -0
package/src/mcp/McpCompileAssertions.d.ts +1 -0
package/src/mcp/McpCompileAssertions.js +65 -0
package/src/mcp/McpCompileAssertions.js.map +1 -0
package/src/mcp/McpMetadata.d.ts +51 -0
package/src/mcp/McpMetadata.js +64 -0
package/src/mcp/McpMetadata.js.map +1 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.763",
+  "version": "0.4.766",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/http/decorators.d.ts CHANGED Viewed

@@ -24,6 +24,8 @@ export declare const METADATA_KEYS: {
     ENDPOINT_CALLER: string;
     /** Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). */
     MASK_LOG: string;
+    /** Per-method opt-in metadata for publishing an RPC endpoint as an MCP tool. */
+    MCP_TOOLS: string;
 };
 /**
  * WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture

package/src/http/decorators.js CHANGED Viewed

@@ -54,6 +54,8 @@ exports.METADATA_KEYS = {
     ENDPOINT_CALLER: external_caller_1.ENDPOINT_CALLER_KEY,
     /** Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). */
     MASK_LOG: 'webpieces:mask-log',
+    /** Per-method opt-in metadata for publishing an RPC endpoint as an MCP tool. */
+    MCP_TOOLS: 'webpieces:mcp-tools',
 };
 /**
  * @ApiPath(basePath) - Class decorator that marks a class as an API definition

package/src/http/decorators.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/decorators.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\nimport { MaskSpec, MaskMode } from './LogFieldMask';\nimport {\n DEFAULT_CALLER_KIND,\n ENDPOINT_CALLER_KEY,\n ExternalCaller,\n ExternalSystemKind,\n getEndpointCaller,\n} from './external-caller';\n// The TYPE layer these decorators attach — split out for file size only (see auth-mode.ts).\nimport { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';\n\n/*\n Metadata keys for storing API routing information.\n * These keys are used by both server-side (routing) and client-side (client generation).\n /\nexport const METADATA_KEYS = {\n API_PATH: 'webpieces:api-path',\n ENDPOINTS: 'webpieces:endpoints',\n AUTH_META: 'webpieces:auth-meta',\n /* Method names carrying one of the canonical authorization decorators. /\n AUTH_METHODS: 'webpieces:auth-methods',\n /* 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). /\n API_KIND: 'webpieces:api-kind',\n /* Per-method Cloud Tasks queue-name override (set via @Queue). /\n QUEUE_OVERRIDE: 'webpieces:queue-override',\n /* Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. /\n ENDPOINT_OPTIONS: 'webpieces:endpoint-options',\n /* Per-method @Endpoint trigger kind (rpc \| cloudtasks \| cron \| external), parallel to ENDPOINTS. /\n ENDPOINT_KIND: 'webpieces:endpoint-kind',\n /* Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. /\n ENDPOINT_CALLER: ENDPOINT_CALLER_KEY,\n /* Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). /\n MASK_LOG: 'webpieces:mask-log',\n};\n\n/\n WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture\n * graph draws it, and which Terraform resource must exist for it to ever fire:\n \n - `rpc` — a caller in this repo (or a browser) calls it synchronously. A direct arrow.\n * - `cloudtasks` — a producer ENQUEUES it; Cloud Tasks delivers it later. Drawn producer → queue →\n * consumer, one queue node per METHOD (see {@link Queue}). Producer and consumer\n * being the SAME service is legal and common — the queue decouples them.\n * - `cron` — a scheduler fires it on a clock. Nothing in-repo calls it; drawn hanging off a\n * clock symbol. Backed by a Cloud Scheduler job.\n * - `external` — a system OUTSIDE this repo drives it (a GCP Pub/Sub push subscription, a Twilio\n * or Gmail webhook). Drawn as an inbound dashed arrow from that system.\n \n Declared PER METHOD, because one api class routinely mixes them: an admin contract can have\n * caller-driven endpoints AND a nightly cron sweep. A class-level marker cannot express that, which\n * is exactly why the graph could not tell these apart before.\n /\nexport type EndpointKind = 'rpc' \| 'cloudtasks' \| 'cron' \| 'external';\n\n/\n Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing\n * `Record<methodName, path>` shape every consumer iterates stays unchanged.\n /\nexport interface EndpointOptions {\n /\n Parse the request body as application/x-www-form-urlencoded (flat key→value) instead of JSON.\n * For EXTERNAL webhooks (e.g. Twilio) that post form-encoded. The request DTO must be FLAT —\n * urlencoded has no nesting (unlike JSON). Default false = JSON.\n /\n formPost?: boolean;\n\n /\n RETAIN the verbatim request bytes + the absolute url the sender addressed, so an\n * {@link WpAuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).\n \n Opt-in PER ENDPOINT, sitting beside `formPost` and for the same reason: the cost lands on the\n * handful of webhook routes rather than on every request in the process. It is retention, not\n * new buffering — the express adapter already accumulates the whole body, it simply threw it\n * away once it had parsed a DTO.\n \n REQUIRED by `@WpAuthWebhook`, checked at wiring time (see\n * {@link assertEveryWebhookEndpointRetainsRawBody}) rather than left to fail as a 401 in\n * production: a hook with nothing to verify is a misconfiguration, not a bad request.\n \n Combines with `formPost` — `{ formPost: true, rawBody: true }` is the Twilio case, where the\n * hook needs the bytes and the url while the controller still wants the flat parsed DTO.\n /\n rawBody?: boolean;\n}\n\n/\n Options for an `external` @Endpoint: everything {@link EndpointOptions} carries, PLUS a REQUIRED\n * declaration of WHO is calling. See {@link Endpoint} for why, `external-caller.ts` for identity.\n /\nexport interface ExternalEndpointOptions extends EndpointOptions {\n /* The outside system that posts here (`'twilio'`) — the graph node IDENTITY, not display text. /\n calledBy: string;\n /* What that caller IS; picks the node's shape. Defaults to `'saas'` (see DEFAULT_CALLER_KIND). /\n callerKind?: ExternalSystemKind;\n}\n\n/\n @ApiPath(basePath) - Class decorator that marks a class as an API definition\n * and sets the base path for all endpoints.\n \n Usage:\n * ```typescript\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n * @WpAuthJwt({ roles: ['admin'] })\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n /\nexport function ApiPath(basePath: string): ClassDecorator {\n return (target: Function) => {\n if (Reflect.hasMetadata('webpieces:ipc-api-id', target)) {\n throw new Error(\n `Class ${target.name \|\| 'Unknown'} cannot combine @ApiPath with @WpInternal.`,\n );\n }\n Reflect.defineMetadata(METADATA_KEYS.API_PATH, basePath, target);\n\n // Initialize endpoints map if not exists\n if (!Reflect.hasMetadata(METADATA_KEYS.ENDPOINTS, target)) {\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, {}, target);\n }\n };\n}\n\n/\n @Endpoint(path, kind, options?) - Method decorator that registers a POST endpoint at the given\n * path and declares WHAT TRIGGERS it.\n \n All endpoints are POST-only (matching gRPC/thrift style).\n \n Usage:\n * ```typescript\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n \n // enqueued by a producer, delivered later by Cloud Tasks:\n * @Endpoint('/send', 'cloudtasks')\n * send(request: SendRequest): Promise<void> { ... }\n \n // fired by Cloud Scheduler on a clock, called by nobody in this repo:\n * @Endpoint('/nightly', 'cron')\n * nightly(request: NightlyRequest): Promise<void> { ... }\n \n // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):\n * @Endpoint('/hook', 'external', { formPost: true, calledBy: 'twilio' })\n * inbound(request: InboundRequest): Promise<InboundResponse> { ... }\n * ```\n \n `kind` is REQUIRED and deliberately positional: it makes every pre-existing single-argument\n * `@Endpoint('/x')` a COMPILE error rather than something a lint rule has to chase, so no endpoint\n * can slip into the runtime architecture graph with its trigger left to guesswork. See\n * {@link EndpointKind} for what each value draws and which Terraform resource backs it.\n \n `calledBy` is REQUIRED for `external` FOR EXACTLY THE SAME REASON, enforced by the overloads below:\n * the one box on the runtime graph whose whole job is to say who calls us from outside could only\n * restate OUR OWN contract name, because nothing in the source ever said who the caller was. This is\n * BREAKING for published consumers, intentionally — an existing `@Endpoint(p, 'external', {...})`\n * stops compiling until it names its caller. Migration is one property; see the migration note in\n * `external-caller.ts`. Non-`external` endpoints are completely unaffected.\n \n The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); kind,\n * options and caller ride PARALLEL ENDPOINT_KIND / ENDPOINT_OPTIONS / ENDPOINT_CALLER maps.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: 'external',\n options: ExternalEndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: Exclude<EndpointKind, 'external'>,\n options?: EndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: EndpointKind,\n options: EndpointOptions = {},\n): MethodDecorator {\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey: string \| symbol, _descriptor: PropertyDescriptor) => {\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n\n const endpoints: Record<string, string> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, metadataTarget) \|\| {};\n\n endpoints[propertyKey as string] = path;\n\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);\n\n const kinds: Record<string, EndpointKind> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, metadataTarget) \|\| {};\n kinds[propertyKey as string] = kind;\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);\n\n const opts: Record<string, EndpointOptions> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) \|\| {};\n opts[propertyKey as string] = options;\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);\n\n // ONLY for 'external', mirroring how a queue name is recorded only for the kinds that HAVE\n // a queue: a caller on an rpc endpoint would be a fact about nothing.\n const declared = options as ExternalEndpointOptions;\n if (\n kind !== 'external' \|\|\n typeof declared.calledBy !== 'string' \|\|\n declared.calledBy === ''\n )\n return;\n const callers: Record<string, ExternalCaller> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) \|\| {};\n callers[propertyKey as string] = new ExternalCaller(\n declared.callerKind ?? DEFAULT_CALLER_KIND,\n declared.calledBy,\n );\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);\n };\n}\n\n/\n @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the\n * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an\n * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire\n * untouched — masking lives in the logging path only.\n \n ```typescript\n * @Endpoint('/account', 'rpc')\n * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })\n * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }\n * ```\n \n Matching is by field NAME at any depth (nested objects + array elements), so\n * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client\n * `[API-client-]` and server `[API-server-]` lines mask it. The spec is read ONCE at route-build\n * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function MaskLog(fields: Record<string, MaskMode>): MethodDecorator {\n const spec = new MaskSpec(fields);\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey: string \| symbol, _descriptor: PropertyDescriptor) => {\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n const specs: Record<string, MaskSpec> =\n Reflect.getMetadata(METADATA_KEYS.MASK_LOG, metadataTarget) \|\| {};\n specs[propertyKey as string] = spec;\n Reflect.defineMetadata(METADATA_KEYS.MASK_LOG, specs, metadataTarget);\n };\n}\n\n/\n The @MaskLog spec for one method, or undefined if the method declared none (the common case — the\n * caller then logs the DTO verbatim on the plain JSON.stringify fast path).\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointOptions\nexport function getMaskSpec(apiClass: Function, methodName: string): MaskSpec \| undefined {\n const specs: Record<string, MaskSpec> =\n Reflect.getMetadata(METADATA_KEYS.MASK_LOG, apiClass) \|\| {};\n return specs[methodName];\n}\n\n/\n Shared implementation for every auth decorator. Authorization is deliberately\n * method-only: a class-level default is too easy to miss when reviewing one endpoint.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nfunction defineAuthMode(mode: AuthMode): MethodDecorator {\n const authMeta = new AuthMeta(mode);\n\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey?: string \| symbol, _descriptor?: PropertyDescriptor) => {\n if (propertyKey === undefined) {\n throw new Error(\n 'Authorization decorators are method-only; annotate every @Endpoint explicitly.',\n );\n }\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n if (Reflect.hasMetadata('webpieces:ipc-api-id', metadataTarget)) {\n throw new Error(\n `Internal API ${metadataTarget.name \|\| 'Unknown'} cannot use HTTP authorization decorators.`,\n );\n }\n validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n const methods = new Set<string>(\n Reflect.getMetadata(METADATA_KEYS.AUTH_METHODS, metadataTarget) \|\| [],\n );\n methods.add(propertyKey as string);\n Reflect.defineMetadata(METADATA_KEYS.AUTH_METHODS, [...methods], metadataTarget);\n };\n}\n\n/\n @WpAuthPublic(reason) - endpoint intentionally requires no authentication.\n * The non-empty reason makes anonymous exposure an explicit review decision.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthPublic(reason: string): MethodDecorator {\n if (typeof reason !== 'string' \|\| reason.trim() === '') {\n throw new Error(\n '@WpAuthPublic requires a non-empty reason explaining why anonymous access is required.',\n );\n }\n return defineAuthMode({ kind: 'public' });\n}\n\n/\n @WpAuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the\n * compiler-enforced role decision ({@link JwtRoles}) plus app-defined fields ({@link JwtRequirement}).\n \n ```typescript\n * @WpAuthJwt({ roles: ['admin', 'editor'] }) // any-of\n * @WpAuthJwt({ allRolesAllowed: true, inOrg: true }) // wide + an app rule enforced by authorizeJwt\n * ```\n \n It absorbed the former `@Auth(requirement)` — same argument, same AuthMode, so two spellings of one\n * decision. One decorator per credential kind now: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /\n * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthJwt(requirement: JwtRequirement): MethodDecorator {\n return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/\n The roles an endpoint accepts, or [] when it accepts every authenticated user. The ONE reader of\n * the {@link JwtRoles} union, so no caller has to re-derive \"does absent mean wide?\" — a question\n * whose two plausible answers is how the widest grant kept hiding behind an absent field.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getAuthMode\nexport function rolesRequired(requirement: JwtRequirement): readonly string[] {\n return requirement.allRolesAllowed === true ? [] : requirement.roles;\n}\n\n/\n @WpAuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service\n * RPC). `callers` is an OPTIONAL app-level allow-list of caller service accounts.\n \n NO args = TRUST THE EDGE: accept any genuine Google-signed OIDC caller, because a PRIVATE Cloud\n * Run service's edge already gates WHO via `run.invoker` IAM (managed in terraform — one source of\n * truth, no hand-synced list in code). If the service is actually PUBLIC, the verifier logs a loud\n * warning (it can't be the gate then). Pass explicit SAs (`@WpAuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthOidc(...callers: string[]): MethodDecorator {\n return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/\n @WpAuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for\n * `key`. `key` is a LOOKUP KEY (not an env var): the server looks up its accepted {@link SharedSecrets}\n * by this key, and each client looks up the value it sends by the SAME key (see {@link Secrets}).\n * For internal callers that cannot mint OIDC tokens.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthSharedSecret(key: string): MethodDecorator {\n return defineAuthMode({ kind: 'shared-secret', secretKey: key });\n}\n\n/\n @WpAuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound\n * `WebhookAuthCallback` proves it. THE mode for every signed inbound webhook — Sentry, GitHub, Stripe, Slack,\n * Twilio — none of which fits the other kinds: no vendor mints Google OIDC tokens, and none sends its\n * secret (they all send a DERIVATION over the request), so `@WpAuthPublic` was the only reachable posture\n * and `calledBy: 'sentry'` stayed a claim rather than a fact.\n \n ```typescript\n * @WpAuthWebhook('sentry')\n * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })\n * abstract notify(request: SentryIssueHook): Promise<HookAck>;\n * ```\n \n `name` is a bare STRING resolved through DI in the server's container, exactly as\n * `@WpAuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a\n * direct reference to a verifier would invert the dependency graph and drag a vendor SDK into the\n * browser bundle that imports the same contract.\n \n THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator\n * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every\n * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).\n * Reimplementing five of those is signing up to track five security changelogs forever and to be\n * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to\n * call the vendor's own library — hence the REQUIRED `{ rawBody: true }` (see\n * {@link EndpointOptions.rawBody}), which is checked at wiring time.\n \n FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.\n * Silently allowing an unverified webhook is the one default that must not exist.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthWebhook(name: string): MethodDecorator {\n return defineAuthMode({ kind: 'webhook', name });\n}\n\n/\n @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`\n * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries\n * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other\n * companies' codebases (POS vendors, back-office platforms, ETL pipelines).\n \n ```typescript\n * @WpAuthApiKey('onetablet-partner', [\n * { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },\n * { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },\n * ])\n * @ApiPath('/management/v1')\n * abstract class ManagementApi { ... }\n * ```\n \n `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as\n * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,\n * and an api contract is level 0, so it never references a verifier directly.\n \n `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator\n * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing\n * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real\n * regime authenticates a PAIR — the key names a customer, a second header names which of that\n * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two\n * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects\n * would mean \"either alone suffices\", which is a load-bearing difference a single-credential shape\n * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are\n * presented in the published document.\n \n The list can never be EMPTY — a contract that declares a key regime and then names no credential\n * would generate a document with no security block, which is the exact silent failure this argument\n * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty\n * tuple, the same device for the same reason).\n \n WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other\n * end, so the framework BELIEVES the trusted context headers that caller forwarded (see\n * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal\n * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone\n * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits\n * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when\n * the hook independently derived the SAME value.\n \n WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a\n * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted\n * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole\n * inbound request instead, so the app owns which headers carry the credential and validates them as a\n * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no\n * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.\n \n FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and\n * `WebhookAuthCallback`.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator {\n return defineAuthMode({ kind: 'apikey', regime, credentials });\n}\n\n/\n @WpAuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not\n * registered as a route at all, and if it is somehow reached it 404s. Method-only, like every\n * authorization decorator, so every endpoint's posture is visible at the method.\n \n ```typescript\n * @WpAuthLocalOnly()\n * @Endpoint('/logs', 'rpc')\n * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }\n * ```\n \n WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in\n * sync by a comment: a route module that registered the route only locally, PLUS a\n * `if (env !== 'local') throw new ApiForbiddenError(...)` at the top of the handler. Neither half\n * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an\n * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,\n * driven by this ONE declaration on the contract, which is where every other \"who may call this\"\n * fact already lives.\n \n It is DELIBERATELY a peer of @WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthApiKey rather than an\n * option on one of them: one decorator per credential kind, and \"local-only\" is a different kind of\n * gate — it authenticates nobody, it excludes an entire environment.\n \n HOW \"local\" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to\n * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint\n * rather than exposing it.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthLocalOnly(): MethodDecorator {\n return defineAuthMode({ kind: 'local-only' });\n}\n\n// ============================================================\n// Helper functions\n// ============================================================\n\n/\n Get the base path from @ApiPath decorator.\n /\nexport function getApiPath(apiClass: Function): string \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/\n Get all endpoints from @Endpoint decorators.\n * Returns a record of methodName -> endpoint path.\n /\nexport function getEndpoints(apiClass: Function): Record<string, string> \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, apiClass);\n}\n\n/\n Every method's declared trigger kind, as `methodName -> kind`. Parallel to {@link getEndpoints}.\n * Empty for a class carrying no @Endpoint at all.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKinds(apiClass: Function): Record<string, EndpointKind> {\n return Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, apiClass) \|\| {};\n}\n\n/\n What triggers ONE method, or undefined when the method carries no @Endpoint.\n \n Defaults to nothing rather than to 'rpc': `kind` is a required argument, so a missing entry means\n * \"this is not an endpoint\", never \"an endpoint that forgot to say\". Silently defaulting here would\n * put an undeclared cron or webhook back into the graph as a normal rpc call — the exact blindness\n * the required argument exists to remove.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKind(apiClass: Function, methodName: string): EndpointKind \| undefined {\n return getEndpointKinds(apiClass)[methodName];\n}\n\n/\n Get the @Endpoint options for one method (empty object if the method had no options).\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions {\n const opts: Record<string, EndpointOptions> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) \|\| {};\n return opts[methodName] ?? {};\n}\n\n/\n Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}\n * overloads already make that a COMPILE error; this is the backstop for the ways TS is bypassed —\n * a JS caller, an `as any` options object, a hand-rolled Reflect.defineMetadata.\n * @throws Error naming the first external endpoint with no `calledBy`.\n /\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryExternalEndpointDeclaresCaller(apiClass: Function): void {\n const kinds = getEndpointKinds(apiClass);\n for (const methodName of Object.keys(kinds)) {\n if (\n kinds[methodName] !== 'external' \|\|\n getEndpointCaller(apiClass, methodName) !== undefined\n )\n continue;\n throw new Error(\n `External endpoint '${methodName}' in ${apiClass.name \|\| 'Unknown'} declares no caller. Say WHO ` +\n `posts to it: @Endpoint(path, 'external', { calledBy: '<vendor>' }) — the runtime architecture ` +\n `graph cannot name an inbound caller it was never told about.`,\n );\n }\n}\n\n/\n True when the method's @Endpoint declared `{ formPost: true }` — its body is\n * application/x-www-form-urlencoded (flat), not JSON.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function isFormPost(apiClass: Function, methodName: string): boolean {\n return getEndpointOptions(apiClass, methodName).formPost === true;\n}\n\n/\n True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the\n * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost\nexport function isRawBody(apiClass: Function, methodName: string): boolean {\n return getEndpointOptions(apiClass, methodName).rawBody === true;\n}\n\n/\n Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the\n * bytes it is supposed to verify. A hook with nothing to verify is a MISCONFIGURATION, and it must\n * surface at startup, naming the fix — not as a 401 in production on exactly the traffic the endpoint\n * exists for.\n \n This pairing is a runtime assert rather than a type because the two halves live on DIFFERENT\n * decorators (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say\n * anything about the other's.\n \n @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.\n /\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void {\n const endpoints = getEndpoints(apiClass) \|\| {};\n for (const methodName of Object.keys(endpoints)) {\n if (\n getAuthMode(apiClass, methodName)?.kind !== 'webhook' \|\|\n isRawBody(apiClass, methodName)\n )\n continue;\n throw new Error(\n `Endpoint '${methodName}' in ${apiClass.name \|\| 'Unknown'} is @WpAuthWebhook but its @Endpoint ` +\n `does not declare { rawBody: true }. A webhook hook verifies a signature over the bytes and ` +\n `the url the SENDER transmitted, and without that option the transport parses the body and ` +\n `throws them away — leaving the hook nothing to check.`,\n );\n }\n}\n\n/\n Check if a class has @ApiPath decorator.\n /\nexport function isApiPath(apiClass: Function): boolean {\n return Reflect.hasMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/\n Get method-level auth metadata. Class-level authorization is forbidden.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator API\nexport function getAuthMeta(apiClass: Function, methodName: string): AuthMeta \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n}\n\n/\n Get the auth mode for a method, or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n /\n// webpieces-disable no-function-outside-class -- typed convenience reader over getAuthMeta\nexport function getAuthMode(apiClass: Function, methodName: string): AuthMode \| undefined {\n return getAuthMeta(apiClass, methodName)?.mode;\n}\n\n/\n The ONE prescription for \"this endpoint declares no auth\", shared by the two places that raise it\n * (here and http-routing's ApiRoutingFactory) because they had drifted into teaching different menus.\n * A message teaching an incomplete API is the same defect as an API with two spellings: whichever menu\n * the caller hits becomes the API they believe exists. It leads with the ROLE-GATED member on purpose —\n * the first thing offered should not be the widest grant.\n /\nexport const MISSING_AUTH_DECORATOR_FIX =\n \"Add one of @WpAuthJwt({roles: ['admin']}) / @WpAuthJwt({allRolesAllowed: true}) / \" +\n '@WpAuthOidc(...callers) / @WpAuthSharedSecret(key) / ' +\n \"@WpAuthWebhook('vendor') / @WpAuthApiKey('regime', [{in: 'header', name: 'x-api-key'}]) / \" +\n \"@WpAuthLocalOnly() / @WpAuthPublic('why anonymous access is required') to \" +\n 'the method.';\n\n/\n Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server\n * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth\n * decorator is a startup error, never a silent open endpoint.\n * @throws Error naming the first endpoint with no auth decorator, via {@link MISSING_AUTH_DECORATOR_FIX}.\n /\nexport function assertEveryEndpointHasAuthMode(apiClass: Function): void {\n const apiName = apiClass.name \|\| 'Unknown';\n const endpoints = getEndpoints(apiClass) \|\| {};\n for (const methodName of Object.keys(endpoints)) {\n if (!getAuthMeta(apiClass, methodName)) {\n throw new Error(\n `Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +\n MISSING_AUTH_DECORATOR_FIX,\n );\n }\n }\n}\n\n/\n Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple auth decorators are found on the same target.\n */\n// webpieces-disable no-function-outside-class -- shared decorator metadata validation\nexport function validateNoConflictingDecorators(\n apiClass: Function,\n methodName: string \| undefined,\n): void {\n const existing = methodName\n ? Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName)\n : Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n\n if (existing) {\n const targetName = apiClass.name \|\| 'Unknown';\n const location = methodName\n ? `method '${methodName}' of ${targetName}`\n : `class ${targetName}`;\n throw new Error(\n `Conflicting auth decorator on ${location}. ` +\n `Only one of @WpAuthJwt({...}) / @WpAuthOidc(...) / @WpAuthSharedSecret(...) / ` +\n `@WpAuthWebhook(...) / @WpAuthApiKey(...) / @WpAuthLocalOnly() / ` +\n `@WpAuthPublic('reason') is allowed per target.`,\n );\n }\n}\n"]}
1	+ {"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/decorators.ts"],"names":[],"mappings":";;;AAiHA,0BAcC;AAsDD,4BA2CC;AAoBD,0BAUC;AAOD,kCAIC;AAsCD,oCAOC;AAgBD,8BAEC;AAQD,sCAEC;AAaD,gCAEC;AASD,gDAEC;AAgCD,sCAEC;AAuDD,oCAEC;AA8BD,0CAEC;AASD,gCAEC;AAMD,oCAEC;AAOD,4CAEC;AAWD,0CAEC;AAMD,gDAIC;AASD,8FAcC;AAOD,gCAEC;AAOD,8BAEC;AAeD,4FAeC;AAKD,8BAEC;AAMD,kCAEC;AAOD,kCAEC;AAsBD,wEAWC;AAOD,0EAoBC;AArrBD,4BAA0B;AAC1B,iDAAoD;AACpD,uDAM2B;AAC3B,4FAA4F;AAC5F,2CAAoF;AAEpF;;;GAGG;AACU,QAAA,aAAa,GAAG;IACzB,QAAQ,EAAE,oBAAoB;IAC9B,SAAS,EAAE,qBAAqB;IAChC,SAAS,EAAE,qBAAqB;IAChC,2EAA2E;IAC3E,YAAY,EAAE,wBAAwB;IACtC,uFAAuF;IACvF,QAAQ,EAAE,oBAAoB;IAC9B,mEAAmE;IACnE,cAAc,EAAE,0BAA0B;IAC1C,2EAA2E;IAC3E,gBAAgB,EAAE,4BAA4B;IAC9C,qGAAqG;IACrG,aAAa,EAAE,yBAAyB;IACxC,6FAA6F;IAC7F,eAAe,EAAE,qCAAmB;IACpC,6EAA6E;IAC7E,QAAQ,EAAE,oBAAoB;IAC9B,gFAAgF;IAChF,SAAS,EAAE,qBAAqB;CACnC,CAAC;AA+DF;;;;;;;;;;;;;GAaG;AACH,SAAgB,OAAO,CAAC,QAAgB;IACpC,OAAO,CAAC,MAAgB,EAAE,EAAE;QACxB,IAAI,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,MAAM,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACX,SAAS,MAAM,CAAC,IAAI,IAAI,SAAS,4CAA4C,CAChF,CAAC;QACN,CAAC;QACD,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEjE,yCAAyC;QACzC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;YACxD,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAChE,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAqDD,2GAA2G;AAC3G,SAAgB,QAAQ,CACpB,IAAY,EACZ,IAAkB,EAClB,UAA2B,EAAE;IAE7B,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,WAA+B,EAAE,EAAE;QAClF,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAElF,MAAM,SAAS,GACX,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAEvE,SAAS,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QAExC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAE3E,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,aAAa,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC3E,KAAK,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QACpC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,aAAa,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;QAE3E,MAAM,IAAI,GACN,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,gBAAgB,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC9E,IAAI,CAAC,WAAqB,CAAC,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,gBAAgB,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAE7E,2FAA2F;QAC3F,sEAAsE;QACtE,MAAM,QAAQ,GAAG,OAAkC,CAAC;QACpD,IACI,IAAI,KAAK,UAAU;YACnB,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ;YACrC,QAAQ,CAAC,QAAQ,KAAK,EAAE;YAExB,OAAO;QACX,MAAM,OAAO,GACT,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,eAAe,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QAC7E,OAAO,CAAC,WAAqB,CAAC,GAAG,IAAI,gCAAc,CAC/C,QAAQ,CAAC,UAAU,IAAI,qCAAmB,EAC1C,QAAQ,CAAC,QAAQ,CACpB,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,eAAe,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IACnF,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,2GAA2G;AAC3G,SAAgB,OAAO,CAAC,MAAgC;IACpD,MAAM,IAAI,GAAG,IAAI,uBAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,WAA+B,EAAE,EAAE;QAClF,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAClF,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,CAAC;QACtE,KAAK,CAAC,WAAqB,CAAC,GAAG,IAAI,CAAC;QACpC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IAC1E,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,wGAAwG;AACxG,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChE,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,2GAA2G;AAC3G,SAAS,cAAc,CAAC,IAAc;IAClC,MAAM,QAAQ,GAAG,IAAI,oBAAQ,CAAC,IAAI,CAAC,CAAC;IAEpC,kFAAkF;IAClF,OAAO,CAAC,MAAW,EAAE,WAA6B,EAAE,WAAgC,EAAE,EAAE;QACpF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACX,gFAAgF,CACnF,CAAC;QACN,CAAC;QACD,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QAClF,IAAI,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,cAAc,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACX,gBAAgB,cAAc,CAAC,IAAI,IAAI,SAAS,4CAA4C,CAC/F,CAAC;QACN,CAAC;QACD,+BAA+B,CAAC,cAAc,EAAE,WAAqB,CAAC,CAAC;QACvE,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;QACvF,MAAM,OAAO,GAAG,IAAI,GAAG,CACnB,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,EAAE,CACxE,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,WAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,cAAc,CAAC,qBAAa,CAAC,YAAY,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC;IACrF,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,2GAA2G;AAC3G,SAAgB,YAAY,CAAC,MAAc;IACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACX,wFAAwF,CAC3F,CAAC;IACN,CAAC;IACD,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,2GAA2G;AAC3G,SAAgB,SAAS,CAAC,WAA2B;IACjD,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,iGAAiG;AACjG,SAAgB,aAAa,CAAC,WAA2B;IACrD,OAAO,WAAW,CAAC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,2GAA2G;AAC3G,SAAgB,UAAU,CAAC,GAAG,OAAiB;IAC3C,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,2GAA2G;AAC3G,SAAgB,kBAAkB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2GAA2G;AAC3G,SAAgB,aAAa,CAAC,IAAY;IACtC,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,2GAA2G;AAC3G,SAAgB,YAAY,CAAC,MAAc,EAAE,WAA8B;IACvE,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,2GAA2G;AAC3G,SAAgB,eAAe;IAC3B,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D;;GAEG;AACH,SAAgB,UAAU,CAAC,QAAkB;IACzC,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,QAAkB;IAC3C,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,kGAAkG;AAClG,SAAgB,gBAAgB,CAAC,QAAkB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,kGAAkG;AAClG,SAAgB,eAAe,CAAC,QAAkB,EAAE,UAAkB;IAClE,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,kGAAkG;AAClG,SAAgB,kBAAkB,CAAC,QAAkB,EAAE,UAAkB;IACrE,MAAM,IAAI,GACN,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxE,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,+GAA+G;AAC/G,SAAgB,yCAAyC,CAAC,QAAkB;IACxE,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACzC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,IACI,KAAK,CAAC,UAAU,CAAC,KAAK,UAAU;YAChC,IAAA,mCAAiB,EAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,SAAS;YAErD,SAAS;QACb,MAAM,IAAI,KAAK,CACX,sBAAsB,UAAU,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,+BAA+B;YAC7F,gGAAgG;YAChG,8DAA8D,CACrE,CAAC;IACN,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,kGAAkG;AAClG,SAAgB,UAAU,CAAC,QAAkB,EAAE,UAAkB;IAC7D,OAAO,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,gGAAgG;AAChG,SAAgB,SAAS,CAAC,QAAkB,EAAE,UAAkB;IAC5D,OAAO,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,+GAA+G;AAC/G,SAAgB,wCAAwC,CAAC,QAAkB;IACvE,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,IACI,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,KAAK,SAAS;YACrD,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC;YAE/B,SAAS;QACb,MAAM,IAAI,KAAK,CACX,aAAa,UAAU,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,uCAAuC;YAC5F,6FAA6F;YAC7F,4FAA4F;YAC5F,uDAAuD,CAC9D,CAAC;IACN,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,QAAkB;IACxC,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,uGAAuG;AACvG,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,OAAO,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,2FAA2F;AAC3F,SAAgB,WAAW,CAAC,QAAkB,EAAE,UAAkB;IAC9D,OAAO,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACU,QAAA,0BAA0B,GACnC,oFAAoF;IACpF,uDAAuD;IACvD,4FAA4F;IAC5F,4EAA4E;IAC5E,aAAa,CAAC;AAElB;;;;;GAKG;AACH,SAAgB,8BAA8B,CAAC,QAAkB;IAC7D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;IAC3C,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACX,aAAa,UAAU,QAAQ,OAAO,0BAA0B;gBAC5D,kCAA0B,CACjC,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,sFAAsF;AACtF,SAAgB,+BAA+B,CAC3C,QAAkB,EAClB,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU;QACvB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC;QACpE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,qBAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE7D,IAAI,QAAQ,EAAE,CAAC;QACX,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;QAC9C,MAAM,QAAQ,GAAG,UAAU;YACvB,CAAC,CAAC,WAAW,UAAU,QAAQ,UAAU,EAAE;YAC3C,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACX,iCAAiC,QAAQ,IAAI;YACzC,gFAAgF;YAChF,kEAAkE;YAClE,gDAAgD,CACvD,CAAC;IACN,CAAC;AACL,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { MaskSpec, MaskMode } from './LogFieldMask';\nimport {\n DEFAULT_CALLER_KIND,\n ENDPOINT_CALLER_KEY,\n ExternalCaller,\n ExternalSystemKind,\n getEndpointCaller,\n} from './external-caller';\n// The TYPE layer these decorators attach — split out for file size only (see auth-mode.ts).\nimport { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';\n\n/*\n Metadata keys for storing API routing information.\n * These keys are used by both server-side (routing) and client-side (client generation).\n /\nexport const METADATA_KEYS = {\n API_PATH: 'webpieces:api-path',\n ENDPOINTS: 'webpieces:endpoints',\n AUTH_META: 'webpieces:auth-meta',\n /* Method names carrying one of the canonical authorization decorators. /\n AUTH_METHODS: 'webpieces:auth-methods',\n /* 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). /\n API_KIND: 'webpieces:api-kind',\n /* Per-method Cloud Tasks queue-name override (set via @Queue). /\n QUEUE_OVERRIDE: 'webpieces:queue-override',\n /* Per-method @Endpoint options (e.g. formPost), parallel to ENDPOINTS. /\n ENDPOINT_OPTIONS: 'webpieces:endpoint-options',\n /* Per-method @Endpoint trigger kind (rpc \| cloudtasks \| cron \| external), parallel to ENDPOINTS. /\n ENDPOINT_KIND: 'webpieces:endpoint-kind',\n /* Per-method declared external CALLER (only for kind 'external'), parallel to ENDPOINTS. /\n ENDPOINT_CALLER: ENDPOINT_CALLER_KEY,\n /* Per-method @MaskLog spec (which DTO fields the LogApiCall path masks). /\n MASK_LOG: 'webpieces:mask-log',\n /* Per-method opt-in metadata for publishing an RPC endpoint as an MCP tool. /\n MCP_TOOLS: 'webpieces:mcp-tools',\n};\n\n/\n WHAT TRIGGERS an endpoint at runtime — the single fact that decides how the runtime architecture\n * graph draws it, and which Terraform resource must exist for it to ever fire:\n \n - `rpc` — a caller in this repo (or a browser) calls it synchronously. A direct arrow.\n * - `cloudtasks` — a producer ENQUEUES it; Cloud Tasks delivers it later. Drawn producer → queue →\n * consumer, one queue node per METHOD (see {@link Queue}). Producer and consumer\n * being the SAME service is legal and common — the queue decouples them.\n * - `cron` — a scheduler fires it on a clock. Nothing in-repo calls it; drawn hanging off a\n * clock symbol. Backed by a Cloud Scheduler job.\n * - `external` — a system OUTSIDE this repo drives it (a GCP Pub/Sub push subscription, a Twilio\n * or Gmail webhook). Drawn as an inbound dashed arrow from that system.\n \n Declared PER METHOD, because one api class routinely mixes them: an admin contract can have\n * caller-driven endpoints AND a nightly cron sweep. A class-level marker cannot express that, which\n * is exactly why the graph could not tell these apart before.\n /\nexport type EndpointKind = 'rpc' \| 'cloudtasks' \| 'cron' \| 'external';\n\n/\n Options for a single @Endpoint. Kept in a metadata map PARALLEL to ENDPOINTS so the existing\n * `Record<methodName, path>` shape every consumer iterates stays unchanged.\n /\nexport interface EndpointOptions {\n /\n Parse the request body as application/x-www-form-urlencoded (flat key→value) instead of JSON.\n * For EXTERNAL webhooks (e.g. Twilio) that post form-encoded. The request DTO must be FLAT —\n * urlencoded has no nesting (unlike JSON). Default false = JSON.\n /\n formPost?: boolean;\n\n /\n RETAIN the verbatim request bytes + the absolute url the sender addressed, so an\n * {@link WpAuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).\n \n Opt-in PER ENDPOINT, sitting beside `formPost` and for the same reason: the cost lands on the\n * handful of webhook routes rather than on every request in the process. It is retention, not\n * new buffering — the express adapter already accumulates the whole body, it simply threw it\n * away once it had parsed a DTO.\n \n REQUIRED by `@WpAuthWebhook`, checked at wiring time (see\n * {@link assertEveryWebhookEndpointRetainsRawBody}) rather than left to fail as a 401 in\n * production: a hook with nothing to verify is a misconfiguration, not a bad request.\n \n Combines with `formPost` — `{ formPost: true, rawBody: true }` is the Twilio case, where the\n * hook needs the bytes and the url while the controller still wants the flat parsed DTO.\n /\n rawBody?: boolean;\n}\n\n/\n Options for an `external` @Endpoint: everything {@link EndpointOptions} carries, PLUS a REQUIRED\n * declaration of WHO is calling. See {@link Endpoint} for why, `external-caller.ts` for identity.\n /\nexport interface ExternalEndpointOptions extends EndpointOptions {\n /* The outside system that posts here (`'twilio'`) — the graph node IDENTITY, not display text. /\n calledBy: string;\n /* What that caller IS; picks the node's shape. Defaults to `'saas'` (see DEFAULT_CALLER_KIND). /\n callerKind?: ExternalSystemKind;\n}\n\n/\n @ApiPath(basePath) - Class decorator that marks a class as an API definition\n * and sets the base path for all endpoints.\n \n Usage:\n * ```typescript\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n * @WpAuthJwt({ roles: ['admin'] })\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n /\nexport function ApiPath(basePath: string): ClassDecorator {\n return (target: Function) => {\n if (Reflect.hasMetadata('webpieces:ipc-api-id', target)) {\n throw new Error(\n `Class ${target.name \|\| 'Unknown'} cannot combine @ApiPath with @WpInternal.`,\n );\n }\n Reflect.defineMetadata(METADATA_KEYS.API_PATH, basePath, target);\n\n // Initialize endpoints map if not exists\n if (!Reflect.hasMetadata(METADATA_KEYS.ENDPOINTS, target)) {\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, {}, target);\n }\n };\n}\n\n/\n @Endpoint(path, kind, options?) - Method decorator that registers a POST endpoint at the given\n * path and declares WHAT TRIGGERS it.\n \n All endpoints are POST-only (matching gRPC/thrift style).\n \n Usage:\n * ```typescript\n * @Endpoint('/item', 'rpc')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n \n // enqueued by a producer, delivered later by Cloud Tasks:\n * @Endpoint('/send', 'cloudtasks')\n * send(request: SendRequest): Promise<void> { ... }\n \n // fired by Cloud Scheduler on a clock, called by nobody in this repo:\n * @Endpoint('/nightly', 'cron')\n * nightly(request: NightlyRequest): Promise<void> { ... }\n \n // EXTERNAL webhook posting application/x-www-form-urlencoded (e.g. Twilio):\n * @Endpoint('/hook', 'external', { formPost: true, calledBy: 'twilio' })\n * inbound(request: InboundRequest): Promise<InboundResponse> { ... }\n * ```\n \n `kind` is REQUIRED and deliberately positional: it makes every pre-existing single-argument\n * `@Endpoint('/x')` a COMPILE error rather than something a lint rule has to chase, so no endpoint\n * can slip into the runtime architecture graph with its trigger left to guesswork. See\n * {@link EndpointKind} for what each value draws and which Terraform resource backs it.\n \n `calledBy` is REQUIRED for `external` FOR EXACTLY THE SAME REASON, enforced by the overloads below:\n * the one box on the runtime graph whose whole job is to say who calls us from outside could only\n * restate OUR OWN contract name, because nothing in the source ever said who the caller was. This is\n * BREAKING for published consumers, intentionally — an existing `@Endpoint(p, 'external', {...})`\n * stops compiling until it names its caller. Migration is one property; see the migration note in\n * `external-caller.ts`. Non-`external` endpoints are completely unaffected.\n \n The path write to ENDPOINTS is UNCHANGED (every consumer iterates `[methodName, path]`); kind,\n * options and caller ride PARALLEL ENDPOINT_KIND / ENDPOINT_OPTIONS / ENDPOINT_CALLER maps.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: 'external',\n options: ExternalEndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: Exclude<EndpointKind, 'external'>,\n options?: EndpointOptions,\n): MethodDecorator;\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function Endpoint(\n path: string,\n kind: EndpointKind,\n options: EndpointOptions = {},\n): MethodDecorator {\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey: string \| symbol, _descriptor: PropertyDescriptor) => {\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n\n const endpoints: Record<string, string> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, metadataTarget) \|\| {};\n\n endpoints[propertyKey as string] = path;\n\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);\n\n const kinds: Record<string, EndpointKind> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, metadataTarget) \|\| {};\n kinds[propertyKey as string] = kind;\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_KIND, kinds, metadataTarget);\n\n const opts: Record<string, EndpointOptions> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, metadataTarget) \|\| {};\n opts[propertyKey as string] = options;\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, opts, metadataTarget);\n\n // ONLY for 'external', mirroring how a queue name is recorded only for the kinds that HAVE\n // a queue: a caller on an rpc endpoint would be a fact about nothing.\n const declared = options as ExternalEndpointOptions;\n if (\n kind !== 'external' \|\|\n typeof declared.calledBy !== 'string' \|\|\n declared.calledBy === ''\n )\n return;\n const callers: Record<string, ExternalCaller> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_CALLER, metadataTarget) \|\| {};\n callers[propertyKey as string] = new ExternalCaller(\n declared.callerKind ?? DEFAULT_CALLER_KIND,\n declared.calledBy,\n );\n Reflect.defineMetadata(METADATA_KEYS.ENDPOINT_CALLER, callers, metadataTarget);\n };\n}\n\n/\n @MaskLog(fields) - declare which fields of THIS method's request/response DTOs the\n * {@link LogApiCallImpl} logging path must mask, so a secret riding on a DTO (an OAuth refresh token, an\n * id-token JWT) is never written to the logs in cleartext. The REAL value still travels on the wire\n * untouched — masking lives in the logging path only.\n \n ```typescript\n * @Endpoint('/account', 'rpc')\n * @MaskLog({ refreshToken: 'full', accessToken: 'last4', credential: 'full' })\n * getEmailAccount(request: GetEmailAccountRequest): Promise<GetEmailAccountResponse> { ... }\n * ```\n \n Matching is by field NAME at any depth (nested objects + array elements), so\n * `response.account.refreshToken` is masked. Declared on the SHARED api contract, so BOTH the client\n * `[API-client-]` and server `[API-server-]` lines mask it. The spec is read ONCE at route-build\n * time and rides {@link RouteMetadata.mask}, so an unmasked method pays nothing at call time.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function MaskLog(fields: Record<string, MaskMode>): MethodDecorator {\n const spec = new MaskSpec(fields);\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey: string \| symbol, _descriptor: PropertyDescriptor) => {\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n const specs: Record<string, MaskSpec> =\n Reflect.getMetadata(METADATA_KEYS.MASK_LOG, metadataTarget) \|\| {};\n specs[propertyKey as string] = spec;\n Reflect.defineMetadata(METADATA_KEYS.MASK_LOG, specs, metadataTarget);\n };\n}\n\n/\n The @MaskLog spec for one method, or undefined if the method declared none (the common case — the\n * caller then logs the DTO verbatim on the plain JSON.stringify fast path).\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpointOptions\nexport function getMaskSpec(apiClass: Function, methodName: string): MaskSpec \| undefined {\n const specs: Record<string, MaskSpec> =\n Reflect.getMetadata(METADATA_KEYS.MASK_LOG, apiClass) \|\| {};\n return specs[methodName];\n}\n\n/\n Shared implementation for every auth decorator. Authorization is deliberately\n * method-only: a class-level default is too easy to miss when reviewing one endpoint.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nfunction defineAuthMode(mode: AuthMode): MethodDecorator {\n const authMeta = new AuthMeta(mode);\n\n // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n return (target: any, propertyKey?: string \| symbol, _descriptor?: PropertyDescriptor) => {\n if (propertyKey === undefined) {\n throw new Error(\n 'Authorization decorators are method-only; annotate every @Endpoint explicitly.',\n );\n }\n const metadataTarget = typeof target === 'function' ? target : target.constructor;\n if (Reflect.hasMetadata('webpieces:ipc-api-id', metadataTarget)) {\n throw new Error(\n `Internal API ${metadataTarget.name \|\| 'Unknown'} cannot use HTTP authorization decorators.`,\n );\n }\n validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n const methods = new Set<string>(\n Reflect.getMetadata(METADATA_KEYS.AUTH_METHODS, metadataTarget) \|\| [],\n );\n methods.add(propertyKey as string);\n Reflect.defineMetadata(METADATA_KEYS.AUTH_METHODS, [...methods], metadataTarget);\n };\n}\n\n/\n @WpAuthPublic(reason) - endpoint intentionally requires no authentication.\n * The non-empty reason makes anonymous exposure an explicit review decision.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthPublic(reason: string): MethodDecorator {\n if (typeof reason !== 'string' \|\| reason.trim() === '') {\n throw new Error(\n '@WpAuthPublic requires a non-empty reason explaining why anonymous access is required.',\n );\n }\n return defineAuthMode({ kind: 'public' });\n}\n\n/\n @WpAuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the\n * compiler-enforced role decision ({@link JwtRoles}) plus app-defined fields ({@link JwtRequirement}).\n \n ```typescript\n * @WpAuthJwt({ roles: ['admin', 'editor'] }) // any-of\n * @WpAuthJwt({ allRolesAllowed: true, inOrg: true }) // wide + an app rule enforced by authorizeJwt\n * ```\n \n It absorbed the former `@Auth(requirement)` — same argument, same AuthMode, so two spellings of one\n * decision. One decorator per credential kind now: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /\n * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthJwt(requirement: JwtRequirement): MethodDecorator {\n return defineAuthMode({ kind: 'jwt', requirement });\n}\n\n/\n The roles an endpoint accepts, or [] when it accepts every authenticated user. The ONE reader of\n * the {@link JwtRoles} union, so no caller has to re-derive \"does absent mean wide?\" — a question\n * whose two plausible answers is how the widest grant kept hiding behind an absent field.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getAuthMode\nexport function rolesRequired(requirement: JwtRequirement): readonly string[] {\n return requirement.allRolesAllowed === true ? [] : requirement.roles;\n}\n\n/\n @WpAuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service\n * RPC). `callers` is an OPTIONAL app-level allow-list of caller service accounts.\n \n NO args = TRUST THE EDGE: accept any genuine Google-signed OIDC caller, because a PRIVATE Cloud\n * Run service's edge already gates WHO via `run.invoker` IAM (managed in terraform — one source of\n * truth, no hand-synced list in code). If the service is actually PUBLIC, the verifier logs a loud\n * warning (it can't be the gate then). Pass explicit SAs (`@WpAuthOidc('svc-a')`) only when you want\n * an additional app-level allow-list as defense-in-depth.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthOidc(...callers: string[]): MethodDecorator {\n return defineAuthMode({ kind: 'oidc', callers });\n}\n\n/\n @WpAuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for\n * `key`. `key` is a LOOKUP KEY (not an env var): the server looks up its accepted {@link SharedSecrets}\n * by this key, and each client looks up the value it sends by the SAME key (see {@link Secrets}).\n * For internal callers that cannot mint OIDC tokens.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthSharedSecret(key: string): MethodDecorator {\n return defineAuthMode({ kind: 'shared-secret', secretKey: key });\n}\n\n/\n @WpAuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound\n * `WebhookAuthCallback` proves it. THE mode for every signed inbound webhook — Sentry, GitHub, Stripe, Slack,\n * Twilio — none of which fits the other kinds: no vendor mints Google OIDC tokens, and none sends its\n * secret (they all send a DERIVATION over the request), so `@WpAuthPublic` was the only reachable posture\n * and `calledBy: 'sentry'` stayed a claim rather than a fact.\n \n ```typescript\n * @WpAuthWebhook('sentry')\n * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })\n * abstract notify(request: SentryIssueHook): Promise<HookAck>;\n * ```\n \n `name` is a bare STRING resolved through DI in the server's container, exactly as\n * `@WpAuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a\n * direct reference to a verifier would invert the dependency graph and drag a vendor SDK into the\n * browser bundle that imports the same contract.\n \n THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator\n * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every\n * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).\n * Reimplementing five of those is signing up to track five security changelogs forever and to be\n * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to\n * call the vendor's own library — hence the REQUIRED `{ rawBody: true }` (see\n * {@link EndpointOptions.rawBody}), which is checked at wiring time.\n \n FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.\n * Silently allowing an unverified webhook is the one default that must not exist.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthWebhook(name: string): MethodDecorator {\n return defineAuthMode({ kind: 'webhook', name });\n}\n\n/\n @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`\n * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries\n * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other\n * companies' codebases (POS vendors, back-office platforms, ETL pipelines).\n \n ```typescript\n * @WpAuthApiKey('onetablet-partner', [\n * { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },\n * { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },\n * ])\n * @ApiPath('/management/v1')\n * abstract class ManagementApi { ... }\n * ```\n \n `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as\n * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,\n * and an api contract is level 0, so it never references a verifier directly.\n \n `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator\n * reading route auth metadata can emit `components.securitySchemes` instead of a human hand-writing\n * them into a manifest. It is a NON-EMPTY, ORDERED list rather than one credential because a real\n * regime authenticates a PAIR — the key names a customer, a second header names which of that\n * customer's organizations the request acts on, and a mismatch is a 401. Its OpenAPI form is two\n * schemes plus ONE security-requirement object holding BOTH keys (an AND); a LIST of two objects\n * would mean \"either alone suffices\", which is a load-bearing difference a single-credential shape\n * cannot even express. ORDER IS SIGNIFICANT and preserved: it is the order the credentials are\n * presented in the published document.\n \n The list can never be EMPTY — a contract that declares a key regime and then names no credential\n * would generate a document with no security block, which is the exact silent failure this argument\n * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty\n * tuple, the same device for the same reason).\n \n WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other\n * end, so the framework BELIEVES the trusted context headers that caller forwarded (see\n * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal\n * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone\n * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits\n * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when\n * the hook independently derived the SAME value.\n \n WHY THE HOOK SEES THE REQUEST, NOT ONE TOKEN. A real key regime checks the key TOGETHER WITH a\n * second header (the organization it is acting for), and `JwtHook.parseJwt` — handed one pre-extracted\n * token from one header — physically cannot. `ApiKeyHook.verifyApiKey(regime, request)` gets the whole\n * inbound request instead, so the app owns which headers carry the credential and validates them as a\n * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no\n * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.\n \n FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and\n * `WebhookAuthCallback`.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator {\n return defineAuthMode({ kind: 'apikey', regime, credentials });\n}\n\n/\n @WpAuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not\n * registered as a route at all, and if it is somehow reached it 404s. Method-only, like every\n * authorization decorator, so every endpoint's posture is visible at the method.\n \n ```typescript\n * @WpAuthLocalOnly()\n * @Endpoint('/logs', 'rpc')\n * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }\n * ```\n \n WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in\n * sync by a comment: a route module that registered the route only locally, PLUS a\n * `if (env !== 'local') throw new ApiForbiddenError(...)` at the top of the handler. Neither half\n * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an\n * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,\n * driven by this ONE declaration on the contract, which is where every other \"who may call this\"\n * fact already lives.\n \n It is DELIBERATELY a peer of @WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthApiKey rather than an\n * option on one of them: one decorator per credential kind, and \"local-only\" is a different kind of\n * gate — it authenticates nobody, it excludes an entire environment.\n \n HOW \"local\" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to\n * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint\n * rather than exposing it.\n /\n// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope\nexport function WpAuthLocalOnly(): MethodDecorator {\n return defineAuthMode({ kind: 'local-only' });\n}\n\n// ============================================================\n// Helper functions\n// ============================================================\n\n/\n Get the base path from @ApiPath decorator.\n /\nexport function getApiPath(apiClass: Function): string \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/\n Get all endpoints from @Endpoint decorators.\n * Returns a record of methodName -> endpoint path.\n /\nexport function getEndpoints(apiClass: Function): Record<string, string> \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, apiClass);\n}\n\n/\n Every method's declared trigger kind, as `methodName -> kind`. Parallel to {@link getEndpoints}.\n * Empty for a class carrying no @Endpoint at all.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKinds(apiClass: Function): Record<string, EndpointKind> {\n return Reflect.getMetadata(METADATA_KEYS.ENDPOINT_KIND, apiClass) \|\| {};\n}\n\n/\n What triggers ONE method, or undefined when the method carries no @Endpoint.\n \n Defaults to nothing rather than to 'rpc': `kind` is a required argument, so a missing entry means\n * \"this is not an endpoint\", never \"an endpoint that forgot to say\". Silently defaulting here would\n * put an undeclared cron or webhook back into the graph as a normal rpc call — the exact blindness\n * the required argument exists to remove.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointKind(apiClass: Function, methodName: string): EndpointKind \| undefined {\n return getEndpointKinds(apiClass)[methodName];\n}\n\n/\n Get the @Endpoint options for one method (empty object if the method had no options).\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function getEndpointOptions(apiClass: Function, methodName: string): EndpointOptions {\n const opts: Record<string, EndpointOptions> =\n Reflect.getMetadata(METADATA_KEYS.ENDPOINT_OPTIONS, apiClass) \|\| {};\n return opts[methodName] ?? {};\n}\n\n/\n Fail-fast at wiring time when an `external` endpoint declared no caller. The {@link Endpoint}\n * overloads already make that a COMPILE error; this is the backstop for the ways TS is bypassed —\n * a JS caller, an `as any` options object, a hand-rolled Reflect.defineMetadata.\n * @throws Error naming the first external endpoint with no `calledBy`.\n /\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryExternalEndpointDeclaresCaller(apiClass: Function): void {\n const kinds = getEndpointKinds(apiClass);\n for (const methodName of Object.keys(kinds)) {\n if (\n kinds[methodName] !== 'external' \|\|\n getEndpointCaller(apiClass, methodName) !== undefined\n )\n continue;\n throw new Error(\n `External endpoint '${methodName}' in ${apiClass.name \|\| 'Unknown'} declares no caller. Say WHO ` +\n `posts to it: @Endpoint(path, 'external', { calledBy: '<vendor>' }) — the runtime architecture ` +\n `graph cannot name an inbound caller it was never told about.`,\n );\n }\n}\n\n/\n True when the method's @Endpoint declared `{ formPost: true }` — its body is\n * application/x-www-form-urlencoded (flat), not JSON.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getEndpoints\nexport function isFormPost(apiClass: Function, methodName: string): boolean {\n return getEndpointOptions(apiClass, methodName).formPost === true;\n}\n\n/\n True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the\n * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost\nexport function isRawBody(apiClass: Function, methodName: string): boolean {\n return getEndpointOptions(apiClass, methodName).rawBody === true;\n}\n\n/\n Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the\n * bytes it is supposed to verify. A hook with nothing to verify is a MISCONFIGURATION, and it must\n * surface at startup, naming the fix — not as a 401 in production on exactly the traffic the endpoint\n * exists for.\n \n This pairing is a runtime assert rather than a type because the two halves live on DIFFERENT\n * decorators (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say\n * anything about the other's.\n \n @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.\n /\n// webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode\nexport function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void {\n const endpoints = getEndpoints(apiClass) \|\| {};\n for (const methodName of Object.keys(endpoints)) {\n if (\n getAuthMode(apiClass, methodName)?.kind !== 'webhook' \|\|\n isRawBody(apiClass, methodName)\n )\n continue;\n throw new Error(\n `Endpoint '${methodName}' in ${apiClass.name \|\| 'Unknown'} is @WpAuthWebhook but its @Endpoint ` +\n `does not declare { rawBody: true }. A webhook hook verifies a signature over the bytes and ` +\n `the url the SENDER transmitted, and without that option the transport parses the body and ` +\n `throws them away — leaving the hook nothing to check.`,\n );\n }\n}\n\n/\n Check if a class has @ApiPath decorator.\n /\nexport function isApiPath(apiClass: Function): boolean {\n return Reflect.hasMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/\n Get method-level auth metadata. Class-level authorization is forbidden.\n /\n// webpieces-disable no-function-outside-class -- reflect-metadata reader paired with the decorator API\nexport function getAuthMeta(apiClass: Function, methodName: string): AuthMeta \| undefined {\n return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n}\n\n/\n Get the auth mode for a method, or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n /\n// webpieces-disable no-function-outside-class -- typed convenience reader over getAuthMeta\nexport function getAuthMode(apiClass: Function, methodName: string): AuthMode \| undefined {\n return getAuthMeta(apiClass, methodName)?.mode;\n}\n\n/\n The ONE prescription for \"this endpoint declares no auth\", shared by the two places that raise it\n * (here and http-routing's ApiRoutingFactory) because they had drifted into teaching different menus.\n * A message teaching an incomplete API is the same defect as an API with two spellings: whichever menu\n * the caller hits becomes the API they believe exists. It leads with the ROLE-GATED member on purpose —\n * the first thing offered should not be the widest grant.\n /\nexport const MISSING_AUTH_DECORATOR_FIX =\n \"Add one of @WpAuthJwt({roles: ['admin']}) / @WpAuthJwt({allRolesAllowed: true}) / \" +\n '@WpAuthOidc(...callers) / @WpAuthSharedSecret(key) / ' +\n \"@WpAuthWebhook('vendor') / @WpAuthApiKey('regime', [{in: 'header', name: 'x-api-key'}]) / \" +\n \"@WpAuthLocalOnly() / @WpAuthPublic('why anonymous access is required') to \" +\n 'the method.';\n\n/\n Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server\n * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth\n * decorator is a startup error, never a silent open endpoint.\n * @throws Error naming the first endpoint with no auth decorator, via {@link MISSING_AUTH_DECORATOR_FIX}.\n /\nexport function assertEveryEndpointHasAuthMode(apiClass: Function): void {\n const apiName = apiClass.name \|\| 'Unknown';\n const endpoints = getEndpoints(apiClass) \|\| {};\n for (const methodName of Object.keys(endpoints)) {\n if (!getAuthMeta(apiClass, methodName)) {\n throw new Error(\n `Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +\n MISSING_AUTH_DECORATOR_FIX,\n );\n }\n }\n}\n\n/\n Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple auth decorators are found on the same target.\n */\n// webpieces-disable no-function-outside-class -- shared decorator metadata validation\nexport function validateNoConflictingDecorators(\n apiClass: Function,\n methodName: string \| undefined,\n): void {\n const existing = methodName\n ? Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName)\n : Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n\n if (existing) {\n const targetName = apiClass.name \|\| 'Unknown';\n const location = methodName\n ? `method '${methodName}' of ${targetName}`\n : `class ${targetName}`;\n throw new Error(\n `Conflicting auth decorator on ${location}. ` +\n `Only one of @WpAuthJwt({...}) / @WpAuthOidc(...) / @WpAuthSharedSecret(...) / ` +\n `@WpAuthWebhook(...) / @WpAuthApiKey(...) / @WpAuthLocalOnly() / ` +\n `@WpAuthPublic('reason') is allowed per target.`,\n );\n }\n}\n"]}

package/src/index.d.ts CHANGED Viewed

@@ -22,6 +22,10 @@ export { WpInternal, WpIpcEndpoint, isInternalApi, getIpcApiId, getIpcEndpoints,
 export type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';
 export { RouteMetadata } from './http/RouteMetadata';
 export type { EndpointKind, EndpointOptions, ExternalEndpointOptions } from './http/decorators';
+export { WpMcpTool, WpMcpToolHints, WpMcpToolMetadata, getWpMcpTools, } from './mcp/McpMetadata';
+export type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';
+export { WpDto, WpDtoField, WpDtoFieldOptions, WpDtoFieldMetadata, WpResponseDto, ApiJsonSchema, DtoValidationFailure, DtoSchemaBuilder, } from './mcp/DtoSchema';
+export type { DtoClass, DtoArrayItem, DtoValue } from './mcp/DtoSchema';
 export { AuthMeta } from './http/auth-mode';
 export type { AuthMode, ApiKeyCredential, ApiKeyCredentials, JwtRoles, JwtRequirement, } from './http/auth-mode';
 export { Rpc, PubSub, Queue, ENDPOINT_KINDS_BY_API_KIND, getApiKind, assertApiKind, assertPubSubConventions, getQueueName, } from './http/api-kind';

package/src/index.js CHANGED Viewed

@@ -9,8 +9,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertInternalApi = exports.getIpcMaskSpec = exports.getIpcEndpointKind = exports.getIpcEndpoints = exports.getIpcApiId = exports.isInternalApi = exports.WpIpcEndpoint = exports.WpInternal = exports.METADATA_KEYS = exports.validateNoConflictingDecorators = exports.assertEveryWebhookEndpointRetainsRawBody = exports.assertEveryExternalEndpointDeclaresCaller = exports.assertEveryEndpointHasAuthMode = exports.getAuthMode = exports.getAuthMeta = exports.isApiPath = exports.isRawBody = exports.isFormPost = exports.getMaskSpec = exports.getEndpointKinds = exports.getEndpointKind = exports.getEndpointOptions = exports.getEndpoints = exports.getApiPath = exports.MaskLog = exports.WpAuthLocalOnly = exports.WpAuthApiKey = exports.WpAuthWebhook = exports.WpAuthSharedSecret = exports.WpAuthOidc = exports.MISSING_AUTH_DECORATOR_FIX = exports.rolesRequired = exports.WpAuthJwt = exports.WpAuthPublic = exports.Endpoint = exports.ApiPath = exports.GCP_LOG_BUDGET_BYTES = exports.MAX_GCP_LOG_BYTES = exports.LogChunkInfo = exports.LogChunkerImpl = exports.LogChunker = exports.LogManager = exports.ConsoleLoggerFactory = exports.ConsoleLogger = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.ContextTuple = exports.ContextKey = exports.toError = void 0;
-exports.ContextMgr = exports.DestinationTrust = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER = exports.WebpiecesDefaultFailureClassifier = exports.KeyedFailureClassifier = exports.HttpResponseDto = exports.HttpResponseStatus = exports.HttpHeader = exports.RuntimeLocality = exports.ServiceInfo = exports.ApiCallTimeoutError = exports.CallContext = exports.CallDeadline = exports.CallRegistry = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NetworkRejectClassifier = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.SECRETS = exports.Secrets = exports.getEndpointCaller = exports.isExternalSystemKind = exports.ExternalCaller = exports.DEFAULT_CALLER_KIND = exports.EXTERNAL_SYSTEM_KINDS = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.ENDPOINT_KINDS_BY_API_KIND = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthMeta = exports.RouteMetadata = exports.IPC_METADATA_KEYS = exports.assertNotInternalApi = void 0;
-exports.ApiErrorHttpStatus = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = exports.FilterChain = exports.Filter = exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.ApiMethodInfo = exports.LOG_API_CALL_LOGGER_NAME = exports.ApiCallLogNameImpl = exports.ApiCallLogName = exports.ApiCallInfo = exports.MaskSpec = exports.LogApiCallImpl = void 0;
+exports.ApiCallTimeoutError = exports.CallContext = exports.CallDeadline = exports.CallRegistry = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NetworkRejectClassifier = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.SECRETS = exports.Secrets = exports.getEndpointCaller = exports.isExternalSystemKind = exports.ExternalCaller = exports.DEFAULT_CALLER_KIND = exports.EXTERNAL_SYSTEM_KINDS = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.ENDPOINT_KINDS_BY_API_KIND = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthMeta = exports.DtoSchemaBuilder = exports.DtoValidationFailure = exports.ApiJsonSchema = exports.WpResponseDto = exports.WpDtoFieldMetadata = exports.WpDtoFieldOptions = exports.WpDtoField = exports.WpDto = exports.getWpMcpTools = exports.WpMcpToolMetadata = exports.WpMcpToolHints = exports.WpMcpTool = exports.RouteMetadata = exports.IPC_METADATA_KEYS = exports.assertNotInternalApi = void 0;
+exports.ApiErrorHttpStatus = exports.ApiErrorPayload = exports.ApiErrorCodec = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = exports.FilterChain = exports.Filter = exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.ApiMethodInfo = exports.LOG_API_CALL_LOGGER_NAME = exports.ApiCallLogNameImpl = exports.ApiCallLogName = exports.ApiCallInfo = exports.MaskSpec = exports.LogApiCallImpl = exports.ContextMgr = exports.DestinationTrust = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER = exports.WebpiecesDefaultFailureClassifier = exports.KeyedFailureClassifier = exports.HttpResponseDto = exports.HttpResponseStatus = exports.HttpHeader = exports.RuntimeLocality = exports.ServiceInfo = void 0;
 var errorUtils_1 = require("./lib/errorUtils");
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errorUtils_1.toError; } });
 var ContextKey_1 = require("./ContextKey");
@@ -86,6 +86,20 @@ Object.defineProperty(exports, "IPC_METADATA_KEYS", { enumerable: true, get: fun
 // The runtime representation of ONE route (split out of decorators.ts for file size only).
 var RouteMetadata_1 = require("./http/RouteMetadata");
 Object.defineProperty(exports, "RouteMetadata", { enumerable: true, get: function () { return RouteMetadata_1.RouteMetadata; } });
+var McpMetadata_1 = require("./mcp/McpMetadata");
+Object.defineProperty(exports, "WpMcpTool", { enumerable: true, get: function () { return McpMetadata_1.WpMcpTool; } });
+Object.defineProperty(exports, "WpMcpToolHints", { enumerable: true, get: function () { return McpMetadata_1.WpMcpToolHints; } });
+Object.defineProperty(exports, "WpMcpToolMetadata", { enumerable: true, get: function () { return McpMetadata_1.WpMcpToolMetadata; } });
+Object.defineProperty(exports, "getWpMcpTools", { enumerable: true, get: function () { return McpMetadata_1.getWpMcpTools; } });
+var DtoSchema_1 = require("./mcp/DtoSchema");
+Object.defineProperty(exports, "WpDto", { enumerable: true, get: function () { return DtoSchema_1.WpDto; } });
+Object.defineProperty(exports, "WpDtoField", { enumerable: true, get: function () { return DtoSchema_1.WpDtoField; } });
+Object.defineProperty(exports, "WpDtoFieldOptions", { enumerable: true, get: function () { return DtoSchema_1.WpDtoFieldOptions; } });
+Object.defineProperty(exports, "WpDtoFieldMetadata", { enumerable: true, get: function () { return DtoSchema_1.WpDtoFieldMetadata; } });
+Object.defineProperty(exports, "WpResponseDto", { enumerable: true, get: function () { return DtoSchema_1.WpResponseDto; } });
+Object.defineProperty(exports, "ApiJsonSchema", { enumerable: true, get: function () { return DtoSchema_1.ApiJsonSchema; } });
+Object.defineProperty(exports, "DtoValidationFailure", { enumerable: true, get: function () { return DtoSchema_1.DtoValidationFailure; } });
+Object.defineProperty(exports, "DtoSchemaBuilder", { enumerable: true, get: function () { return DtoSchema_1.DtoSchemaBuilder; } });
 // The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.
 var auth_mode_1 = require("./http/auth-mode");
 Object.defineProperty(exports, "AuthMeta", { enumerable: true, get: function () { return auth_mode_1.AuthMeta; } });

package/src/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n @webpieces/core-util\n \n Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n \n @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n AnyContextKey,\n AnyTrustedContextKey,\n AnyUntrustedContextKey,\n Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n LogChunker,\n LogChunkerImpl,\n LogChunkInfo,\n MAX_GCP_LOG_BYTES,\n GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n ApiPath,\n Endpoint,\n // Auth mode decorators (clean service-to-service + user JWT model)\n WpAuthPublic,\n WpAuthJwt,\n rolesRequired,\n MISSING_AUTH_DECORATOR_FIX,\n WpAuthOidc,\n WpAuthSharedSecret,\n WpAuthWebhook,\n WpAuthApiKey,\n WpAuthLocalOnly,\n MaskLog,\n getApiPath,\n getEndpoints,\n getEndpointOptions,\n getEndpointKind,\n getEndpointKinds,\n getMaskSpec,\n isFormPost,\n isRawBody,\n isApiPath,\n getAuthMeta,\n getAuthMode,\n assertEveryEndpointHasAuthMode,\n assertEveryExternalEndpointDeclaresCaller,\n assertEveryWebhookEndpointRetainsRawBody,\n validateNoConflictingDecorators,\n METADATA_KEYS,\n} from './http/decorators';\nexport {\n WpInternal,\n WpIpcEndpoint,\n isInternalApi,\n getIpcApiId,\n getIpcEndpoints,\n getIpcEndpointKind,\n getIpcMaskSpec,\n assertInternalApi,\n assertNotInternalApi,\n IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport type { EndpointKind, EndpointOptions, ExternalEndpointOptions } from './http/decorators';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n AuthMode,\n ApiKeyCredential,\n ApiKeyCredentials,\n JwtRoles,\n JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n Rpc,\n PubSub,\n Queue,\n ENDPOINT_KINDS_BY_API_KIND,\n getApiKind,\n assertApiKind,\n assertPubSubConventions,\n getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration @Endpoint(..., 'external', {calledBy})\n// requires, and the reader for it.\nexport {\n EXTERNAL_SYSTEM_KINDS,\n DEFAULT_CALLER_KIND,\n ExternalCaller,\n isExternalSystemKind,\n getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\nexport {\n ENTITY_NOT_FOUND,\n WRONG_LOGIN_TYPE,\n WRONG_LOGIN,\n NOT_APPROVED,\n EMAIL_NOT_CONFIRMED,\n WRONG_DOMAIN,\n WRONG_COMPANY,\n NO_REG_CODE,\n} from './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n InstantDto,\n DateDto,\n TimeDto,\n DateTimeDto,\n InstantUtil,\n DateUtil,\n TimeUtil,\n DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslators implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslators } from './http/ErrorTranslators';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n WebpiecesDefaultFailureClassifier,\n WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n ApiCallLogName,\n ApiCallLogNameImpl,\n LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n RecordedEndpoint,\n RecordedError,\n RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n ApiError,\n ApiNotFoundError,\n ApiDependencyError,\n ApiUnavailableError,\n ApiDependencyTimeoutError,\n ApiImplementationError,\n ApiRateLimitedError,\n ApiForbiddenError,\n ApiRequestTimeoutError,\n ApiEndUserError,\n ApiBadRequestError,\n ApiUnauthorizedError,\n ApiDependencyBackoffError,\n ApiConnectionError,\n ApiEndpointNotFoundError,\n ApiErrorCodec,\n ApiErrorPayload,\n} from './errors';\nexport type { ApiErrorKind } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\n"]}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n @webpieces/core-util\n \n Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n \n @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n AnyContextKey,\n AnyTrustedContextKey,\n AnyUntrustedContextKey,\n Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n LogChunker,\n LogChunkerImpl,\n LogChunkInfo,\n MAX_GCP_LOG_BYTES,\n GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n ApiPath,\n Endpoint,\n // Auth mode decorators (clean service-to-service + user JWT model)\n WpAuthPublic,\n WpAuthJwt,\n rolesRequired,\n MISSING_AUTH_DECORATOR_FIX,\n WpAuthOidc,\n WpAuthSharedSecret,\n WpAuthWebhook,\n WpAuthApiKey,\n WpAuthLocalOnly,\n MaskLog,\n getApiPath,\n getEndpoints,\n getEndpointOptions,\n getEndpointKind,\n getEndpointKinds,\n getMaskSpec,\n isFormPost,\n isRawBody,\n isApiPath,\n getAuthMeta,\n getAuthMode,\n assertEveryEndpointHasAuthMode,\n assertEveryExternalEndpointDeclaresCaller,\n assertEveryWebhookEndpointRetainsRawBody,\n validateNoConflictingDecorators,\n METADATA_KEYS,\n} from './http/decorators';\nexport {\n WpInternal,\n WpIpcEndpoint,\n isInternalApi,\n getIpcApiId,\n getIpcEndpoints,\n getIpcEndpointKind,\n getIpcMaskSpec,\n assertInternalApi,\n assertNotInternalApi,\n IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport type { EndpointKind, EndpointOptions, ExternalEndpointOptions } from './http/decorators';\nexport {\n WpMcpTool,\n WpMcpToolHints,\n WpMcpToolMetadata,\n getWpMcpTools,\n} from './mcp/McpMetadata';\nexport type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';\nexport {\n WpDto,\n WpDtoField,\n WpDtoFieldOptions,\n WpDtoFieldMetadata,\n WpResponseDto,\n ApiJsonSchema,\n DtoValidationFailure,\n DtoSchemaBuilder,\n} from './mcp/DtoSchema';\nexport type { DtoClass, DtoArrayItem, DtoValue } from './mcp/DtoSchema';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n AuthMode,\n ApiKeyCredential,\n ApiKeyCredentials,\n JwtRoles,\n JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n Rpc,\n PubSub,\n Queue,\n ENDPOINT_KINDS_BY_API_KIND,\n getApiKind,\n assertApiKind,\n assertPubSubConventions,\n getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration @Endpoint(..., 'external', {calledBy})\n// requires, and the reader for it.\nexport {\n EXTERNAL_SYSTEM_KINDS,\n DEFAULT_CALLER_KIND,\n ExternalCaller,\n isExternalSystemKind,\n getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\nexport {\n ENTITY_NOT_FOUND,\n WRONG_LOGIN_TYPE,\n WRONG_LOGIN,\n NOT_APPROVED,\n EMAIL_NOT_CONFIRMED,\n WRONG_DOMAIN,\n WRONG_COMPANY,\n NO_REG_CODE,\n} from './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n InstantDto,\n DateDto,\n TimeDto,\n DateTimeDto,\n InstantUtil,\n DateUtil,\n TimeUtil,\n DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslators implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslators } from './http/ErrorTranslators';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n WebpiecesDefaultFailureClassifier,\n WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n ApiCallLogName,\n ApiCallLogNameImpl,\n LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n RecordedEndpoint,\n RecordedError,\n RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n ApiError,\n ApiNotFoundError,\n ApiDependencyError,\n ApiUnavailableError,\n ApiDependencyTimeoutError,\n ApiImplementationError,\n ApiRateLimitedError,\n ApiForbiddenError,\n ApiRequestTimeoutError,\n ApiEndUserError,\n ApiBadRequestError,\n ApiUnauthorizedError,\n ApiDependencyBackoffError,\n ApiConnectionError,\n ApiEndpointNotFoundError,\n ApiErrorCodec,\n ApiErrorPayload,\n} from './errors';\nexport type { ApiErrorKind } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\n"]}

package/src/mcp/DtoSchema.d.ts ADDED Viewed

@@ -0,0 +1,70 @@
+import 'reflect-metadata';
+export type DtoClass = abstract new (...args: any[]) => unknown;
+export type DtoArrayItem = 'string' | 'number' | 'integer' | 'boolean' | DtoClass;
+/** Runtime values accepted at the DTO validation boundary. */
+export type DtoValue = object | string | number | boolean | null;
+/** Additive field metadata; the scalar/object type itself comes from `design:type`. */
+export declare class WpDtoFieldOptions {
+    readonly description: string;
+    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
+    readonly required: boolean;
+    /** Required for arrays because TypeScript erases their element type. */
+    readonly arrayItems?: DtoArrayItem | undefined;
+    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
+    readonly integer: boolean;
+    readonly minimum?: number | undefined;
+    readonly maximum?: number | undefined;
+    readonly enumValues?: readonly [string, ...string[]] | undefined;
+    constructor(description: string,
+    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
+    required: boolean,
+    /** Required for arrays because TypeScript erases their element type. */
+    arrayItems?: DtoArrayItem | undefined,
+    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
+    integer?: boolean, minimum?: number | undefined, maximum?: number | undefined, enumValues?: readonly [string, ...string[]] | undefined);
+}
+export declare class WpDtoFieldMetadata {
+    readonly propertyKey: string;
+    readonly options: WpDtoFieldOptions;
+    constructor(propertyKey: string, options: WpDtoFieldOptions);
+}
+/** The JSON Schema subset emitted for Webpieces API DTOs. */
+export declare class ApiJsonSchema {
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    properties?: Record<string, ApiJsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: ApiJsonSchema;
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    constructor(type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array');
+}
+/** A validation result safe to show to an API caller/model. */
+export declare class DtoValidationFailure {
+    readonly message: string;
+    constructor(message: string);
+}
+/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */
+export declare function WpDto(): ClassDecorator;
+/** Adds documentation and runtime-only shape facts to a DTO property. */
+export declare function WpDtoField(options: WpDtoFieldOptions): PropertyDecorator;
+/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */
+export declare function WpResponseDto(responseDto: () => DtoClass): MethodDecorator;
+/** Builds and validates the same DTO schema used for MCP input and structured output. */
+export declare class DtoSchemaBuilder {
+    requestClassOf(apiClass: Function, methodName: string): DtoClass;
+    responseClassOf(apiClass: Function, methodName: string): DtoClass;
+    build(dtoClass: DtoClass): ApiJsonSchema;
+    validate(dtoClass: DtoClass, value: DtoValue): DtoValidationFailure | undefined;
+    private buildAt;
+    private fieldSchema;
+    private validateOptions;
+    private itemSchema;
+    private validateAt;
+    private validateField;
+    private validateArray;
+    private fields;
+    private requireDto;
+}

package/src/mcp/DtoSchema.js ADDED Viewed

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DtoSchemaBuilder = exports.DtoValidationFailure = exports.ApiJsonSchema = exports.WpDtoFieldMetadata = exports.WpDtoFieldOptions = void 0;
+exports.WpDto = WpDto;
+exports.WpDtoField = WpDtoField;
+exports.WpResponseDto = WpResponseDto;
+require("reflect-metadata");
+const DTO_MARKER = 'webpieces:dto-schema';
+const DTO_FIELDS = 'webpieces:dto-fields';
+const RESPONSE_DTOS = 'webpieces:response-dtos';
+/** Additive field metadata; the scalar/object type itself comes from `design:type`. */
+class WpDtoFieldOptions {
+    description;
+    required;
+    arrayItems;
+    integer;
+    minimum;
+    maximum;
+    enumValues;
+    constructor(description,
+    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
+    required,
+    /** Required for arrays because TypeScript erases their element type. */
+    arrayItems,
+    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
+    integer = false, minimum, maximum, enumValues) {
+        this.description = description;
+        this.required = required;
+        this.arrayItems = arrayItems;
+        this.integer = integer;
+        this.minimum = minimum;
+        this.maximum = maximum;
+        this.enumValues = enumValues;
+    }
+}
+exports.WpDtoFieldOptions = WpDtoFieldOptions;
+class WpDtoFieldMetadata {
+    propertyKey;
+    options;
+    constructor(propertyKey, options) {
+        this.propertyKey = propertyKey;
+        this.options = options;
+    }
+}
+exports.WpDtoFieldMetadata = WpDtoFieldMetadata;
+/** The JSON Schema subset emitted for Webpieces API DTOs. */
+class ApiJsonSchema {
+    type;
+    description;
+    properties;
+    required;
+    additionalProperties;
+    items;
+    enum;
+    minimum;
+    maximum;
+    constructor(type) {
+        this.type = type;
+    }
+}
+exports.ApiJsonSchema = ApiJsonSchema;
+/** A validation result safe to show to an API caller/model. */
+class DtoValidationFailure {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+}
+exports.DtoValidationFailure = DtoValidationFailure;
+/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */
+// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
+function WpDto() {
+    return (target) => Reflect.defineMetadata(DTO_MARKER, true, target);
+}
+/** Adds documentation and runtime-only shape facts to a DTO property. */
+// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
+function WpDtoField(options) {
+    if (options.description.trim() === '') {
+        throw new Error('@WpDtoField requires non-empty field documentation.');
+    }
+    return (target, propertyKey) => {
+        const dtoClass = target.constructor;
+        const fields = Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};
+        const name = String(propertyKey);
+        fields[name] = new WpDtoFieldMetadata(name, options);
+        Reflect.defineMetadata(DTO_FIELDS, fields, dtoClass);
+    };
+}
+/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */
+// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
+function WpResponseDto(responseDto) {
+    return (target, propertyKey) => {
+        const apiClass = target.constructor;
+        const responses = Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};
+        responses[String(propertyKey)] = responseDto;
+        Reflect.defineMetadata(RESPONSE_DTOS, responses, apiClass);
+    };
+}
+/** Builds and validates the same DTO schema used for MCP input and structured output. */
+class DtoSchemaBuilder {
+    requestClassOf(apiClass, methodName) {
+        // webpieces-disable no-any-unknown -- reflect-metadata returns erased runtime constructor tokens
+        const params = Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName);
+        if (!params || params.length !== 1) {
+            throw new Error(`${apiClass.name}.${methodName} must take exactly one @WpDto request class to be an MCP tool.`);
+        }
+        return params[0];
+    }
+    responseClassOf(apiClass, methodName) {
+        const responses = Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};
+        const response = responses[methodName];
+        if (!response) {
+            throw new Error(`${apiClass.name}.${methodName} must declare @WpResponseDto(() => ResponseClass) before MCP exposure.`);
+        }
+        return response();
+    }
+    build(dtoClass) {
+        return this.buildAt(dtoClass, new Set());
+    }
+    validate(dtoClass, value) {
+        return this.validateAt(dtoClass, value, '$');
+    }
+    buildAt(dtoClass, parents) {
+        this.requireDto(dtoClass);
+        if (parents.has(dtoClass)) {
+            throw new Error(`Recursive DTO ${dtoClass.name} cannot use an inline MCP schema.`);
+        }
+        const nextParents = new Set(parents);
+        nextParents.add(dtoClass);
+        const schema = new ApiJsonSchema('object');
+        schema.properties = {};
+        schema.additionalProperties = false;
+        const required = [];
+        for (const field of this.fields(dtoClass)) {
+            schema.properties[field.propertyKey] = this.fieldSchema(dtoClass, field, nextParents);
+            if (field.options.required)
+                required.push(field.propertyKey);
+        }
+        if (required.length > 0)
+            schema.required = required;
+        return schema;
+    }
+    fieldSchema(dtoClass, field, parents) {
+        // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token
+        const reflected = Reflect.getMetadata('design:type', dtoClass.prototype, field.propertyKey);
+        if (!reflected)
+            throw new Error(`No reflected type for ${dtoClass.name}.${field.propertyKey}.`);
+        const options = field.options;
+        this.validateOptions(dtoClass, field, reflected);
+        let schema;
+        switch (reflected.name) {
+            case 'String':
+                schema = new ApiJsonSchema('string');
+                break;
+            case 'Number':
+                schema = new ApiJsonSchema(options.integer ? 'integer' : 'number');
+                break;
+            case 'Boolean':
+                schema = new ApiJsonSchema('boolean');
+                break;
+            case 'Array':
+                if (!options.arrayItems) {
+                    throw new Error(`${dtoClass.name}.${field.propertyKey} must declare arrayItems.`);
+                }
+                schema = new ApiJsonSchema('array');
+                schema.items = this.itemSchema(options.arrayItems, parents);
+                break;
+            default:
+                schema = this.buildAt(reflected, parents);
+        }
+        schema.description = options.description;
+        if (options.minimum !== undefined)
+            schema.minimum = options.minimum;
+        if (options.maximum !== undefined)
+            schema.maximum = options.maximum;
+        if (options.enumValues)
+            schema.enum = [...options.enumValues];
+        return schema;
+    }
+    validateOptions(dtoClass, field, reflected) {
+        const label = `${dtoClass.name}.${field.propertyKey}`;
+        const options = field.options;
+        if (reflected.name !== 'Array' && options.arrayItems) {
+            throw new Error(`${label} declares arrayItems but is not an array.`);
+        }
+        if (reflected.name !== 'Number' &&
+            (options.integer || options.minimum !== undefined || options.maximum !== undefined)) {
+            throw new Error(`${label} declares numeric constraints but is not a number.`);
+        }
+        if (options.minimum !== undefined && options.maximum !== undefined && options.minimum > options.maximum) {
+            throw new Error(`${label} minimum cannot exceed maximum.`);
+        }
+        if (options.enumValues && reflected.name !== 'String') {
+            throw new Error(`${label} enumValues require a string field.`);
+        }
+    }
+    itemSchema(item, parents) {
+        if (typeof item !== 'string')
+            return this.buildAt(item, parents);
+        return new ApiJsonSchema(item === 'integer' ? 'integer' : item);
+    }
+    validateAt(dtoClass, value, path) {
+        this.requireDto(dtoClass);
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return new DtoValidationFailure(`${path} must be an object`);
+        }
+        const fields = this.fields(dtoClass);
+        const known = new Set(fields.map((field) => field.propertyKey));
+        for (const key of Object.keys(value)) {
+            if (!known.has(key))
+                return new DtoValidationFailure(`${path}.${key} is not allowed`);
+        }
+        for (const field of fields) {
+            const fieldValue = Object.getOwnPropertyDescriptor(value, field.propertyKey)?.value;
+            if (fieldValue === undefined) {
+                if (field.options.required) {
+                    return new DtoValidationFailure(`${path}.${field.propertyKey} is required`);
+                }
+                continue;
+            }
+            const failure = this.validateField(dtoClass, field, fieldValue, `${path}.${field.propertyKey}`);
+            if (failure)
+                return failure;
+        }
+        return undefined;
+    }
+    validateField(dtoClass, field, value, path) {
+        // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token
+        const reflected = Reflect.getMetadata('design:type', dtoClass.prototype, field.propertyKey);
+        const expected = reflected?.name;
+        if (expected === 'Array')
+            return this.validateArray(field.options, value, path);
+        if (expected === 'String') {
+            if (typeof value !== 'string')
+                return new DtoValidationFailure(`${path} must be a string`);
+            if (field.options.enumValues && !field.options.enumValues.includes(value)) {
+                return new DtoValidationFailure(`${path} must be one of: ${field.options.enumValues.join(', ')}`);
+            }
+            return undefined;
+        }
+        if (expected === 'Number') {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return new DtoValidationFailure(`${path} must be a number`);
+            }
+            if (field.options.integer && !Number.isInteger(value)) {
+                return new DtoValidationFailure(`${path} must be an integer`);
+            }
+            if (field.options.minimum !== undefined && value < field.options.minimum) {
+                return new DtoValidationFailure(`${path} must be >= ${field.options.minimum}`);
+            }
+            if (field.options.maximum !== undefined && value > field.options.maximum) {
+                return new DtoValidationFailure(`${path} must be <= ${field.options.maximum}`);
+            }
+            return undefined;
+        }
+        if (expected === 'Boolean') {
+            return typeof value === 'boolean'
+                ? undefined
+                : new DtoValidationFailure(`${path} must be a boolean`);
+        }
+        return this.validateAt(reflected, value, path);
+    }
+    validateArray(options, value, path) {
+        if (!Array.isArray(value))
+            return new DtoValidationFailure(`${path} must be an array`);
+        if (!options.arrayItems)
+            return new DtoValidationFailure(`${path} has no item type`);
+        for (let index = 0; index < value.length; index += 1) {
+            const item = value[index];
+            if (typeof options.arrayItems !== 'string') {
+                const nested = this.validateAt(options.arrayItems, item, `${path}[${index}]`);
+                if (nested)
+                    return nested;
+                continue;
+            }
+            const wanted = options.arrayItems === 'integer' ? 'number' : options.arrayItems;
+            if (typeof item !== wanted || (options.arrayItems === 'integer' && !Number.isInteger(item))) {
+                return new DtoValidationFailure(`${path}[${index}] must be ${options.arrayItems}`);
+            }
+        }
+        return undefined;
+    }
+    fields(dtoClass) {
+        const fields = Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};
+        return Object.values(fields);
+    }
+    requireDto(dtoClass) {
+        if (!Reflect.getMetadata(DTO_MARKER, dtoClass)) {
+            throw new Error(`${dtoClass.name} must be decorated with @WpDto() for schema generation.`);
+        }
+    }
+}
+exports.DtoSchemaBuilder = DtoSchemaBuilder;
+//# sourceMappingURL=DtoSchema.js.map

package/src/mcp/DtoSchema.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"DtoSchema.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/DtoSchema.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\n\nconst DTO_MARKER = 'webpieces:dto-schema';\nconst DTO_FIELDS = 'webpieces:dto-fields';\nconst RESPONSE_DTOS = 'webpieces:response-dtos';\n\n// webpieces-disable no-any-unknown -- abstract class tokens necessarily erase constructor parameters\nexport type DtoClass = abstract new (...args: any[]) => unknown;\nexport type DtoArrayItem = 'string' | 'number' | 'integer' | 'boolean' | DtoClass;\n/** Runtime values accepted at the DTO validation boundary. */\nexport type DtoValue = object | string | number | boolean | null;\n\n/** Additive field metadata; the scalar/object type itself comes from `design:type`. */\nexport class WpDtoFieldOptions {\n constructor(\n public readonly description: string,\n /** Required/optional is explicit because TypeScript erases `?` at runtime. */\n public readonly required: boolean,\n /** Required for arrays because TypeScript erases their element type. */\n public readonly arrayItems?: DtoArrayItem,\n /** A reflected Number is otherwise emitted as JSON Schema `number`. */\n public readonly integer: boolean = false,\n public readonly minimum?: number,\n public readonly maximum?: number,\n public readonly enumValues?: readonly [string, ...string[]],\n ) {}\n}\n\nexport class WpDtoFieldMetadata {\n constructor(\n public readonly propertyKey: string,\n public readonly options: WpDtoFieldOptions,\n ) {}\n}\n\n/** The JSON Schema subset emitted for Webpieces API DTOs. */\nexport class ApiJsonSchema {\n type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array';\n description?: string;\n properties?: Record<string, ApiJsonSchema>;\n required?: string[];\n additionalProperties?: boolean;\n items?: ApiJsonSchema;\n enum?: string[];\n minimum?: number;\n maximum?: number;\n\n constructor(type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array') {\n this.type = type;\n }\n}\n\n/** A validation result safe to show to an API caller/model. */\nexport class DtoValidationFailure {\n constructor(public readonly message: string) {}\n}\n\n/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpDto(): ClassDecorator {\n return (target: Function): void => Reflect.defineMetadata(DTO_MARKER, true, target);\n}\n\n/** Adds documentation and runtime-only shape facts to a DTO property. */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpDtoField(options: WpDtoFieldOptions): PropertyDecorator {\n if (options.description.trim() === '') {\n throw new Error('@WpDtoField requires non-empty field documentation.');\n }\n return (target: object, propertyKey: string | symbol): void => {\n const dtoClass = target.constructor;\n const fields: Record<string, WpDtoFieldMetadata> =\n Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};\n const name = String(propertyKey);\n fields[name] = new WpDtoFieldMetadata(name, options);\n Reflect.defineMetadata(DTO_FIELDS, fields, dtoClass);\n };\n}\n\n/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpResponseDto(responseDto: () => DtoClass): MethodDecorator {\n return (target: object, propertyKey: string | symbol): void => {\n const apiClass = target.constructor;\n const responses: Record<string, () => DtoClass> =\n Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};\n responses[String(propertyKey)] = responseDto;\n Reflect.defineMetadata(RESPONSE_DTOS, responses, apiClass);\n };\n}\n\n/** Builds and validates the same DTO schema used for MCP input and structured output. */\nexport class DtoSchemaBuilder {\n requestClassOf(apiClass: Function, methodName: string): DtoClass {\n // webpieces-disable no-any-unknown -- reflect-metadata returns erased runtime constructor tokens\n const params = Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName) as\n | DtoClass[]\n | undefined;\n if (!params || params.length !== 1) {\n throw new Error(\n `${apiClass.name}.${methodName} must take exactly one @WpDto request class to be an MCP tool.`,\n );\n }\n return params[0];\n }\n\n responseClassOf(apiClass: Function, methodName: string): DtoClass {\n const responses: Record<string, () => DtoClass> =\n Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};\n const response = responses[methodName];\n if (!response) {\n throw new Error(\n `${apiClass.name}.${methodName} must declare @WpResponseDto(() => ResponseClass) before MCP exposure.`,\n );\n }\n return response();\n }\n\n build(dtoClass: DtoClass): ApiJsonSchema {\n return this.buildAt(dtoClass, new Set<DtoClass>());\n }\n\n validate(dtoClass: DtoClass, value: DtoValue): DtoValidationFailure | undefined {\n return this.validateAt(dtoClass, value, '$');\n }\n\n private buildAt(dtoClass: DtoClass, parents: Set<DtoClass>): ApiJsonSchema {\n this.requireDto(dtoClass);\n if (parents.has(dtoClass)) {\n throw new Error(`Recursive DTO ${dtoClass.name} cannot use an inline MCP schema.`);\n }\n const nextParents = new Set(parents);\n nextParents.add(dtoClass);\n const schema = new ApiJsonSchema('object');\n schema.properties = {};\n schema.additionalProperties = false;\n const required: string[] = [];\n for (const field of this.fields(dtoClass)) {\n schema.properties[field.propertyKey] = this.fieldSchema(dtoClass, field, nextParents);\n if (field.options.required) required.push(field.propertyKey);\n }\n if (required.length > 0) schema.required = required;\n return schema;\n }\n\n private fieldSchema(\n dtoClass: DtoClass,\n field: WpDtoFieldMetadata,\n parents: Set<DtoClass>,\n ): ApiJsonSchema {\n // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token\n const reflected = Reflect.getMetadata(\n 'design:type',\n dtoClass.prototype,\n field.propertyKey,\n ) as DtoClass | undefined;\n if (!reflected) throw new Error(`No reflected type for ${dtoClass.name}.${field.propertyKey}.`);\n const options = field.options;\n this.validateOptions(dtoClass, field, reflected);\n let schema: ApiJsonSchema;\n switch (reflected.name) {\n case 'String':\n schema = new ApiJsonSchema('string');\n break;\n case 'Number':\n schema = new ApiJsonSchema(options.integer ? 'integer' : 'number');\n break;\n case 'Boolean':\n schema = new ApiJsonSchema('boolean');\n break;\n case 'Array':\n if (!options.arrayItems) {\n throw new Error(`${dtoClass.name}.${field.propertyKey} must declare arrayItems.`);\n }\n schema = new ApiJsonSchema('array');\n schema.items = this.itemSchema(options.arrayItems, parents);\n break;\n default:\n schema = this.buildAt(reflected, parents);\n }\n schema.description = options.description;\n if (options.minimum !== undefined) schema.minimum = options.minimum;\n if (options.maximum !== undefined) schema.maximum = options.maximum;\n if (options.enumValues) schema.enum = [...options.enumValues];\n return schema;\n }\n\n private validateOptions(\n dtoClass: DtoClass,\n field: WpDtoFieldMetadata,\n reflected: DtoClass,\n ): void {\n const label = `${dtoClass.name}.${field.propertyKey}`;\n const options = field.options;\n if (reflected.name !== 'Array' && options.arrayItems) {\n throw new Error(`${label} declares arrayItems but is not an array.`);\n }\n if (\n reflected.name !== 'Number' &&\n (options.integer || options.minimum !== undefined || options.maximum !== undefined)\n ) {\n throw new Error(`${label} declares numeric constraints but is not a number.`);\n }\n if (options.minimum !== undefined && options.maximum !== undefined && options.minimum > options.maximum) {\n throw new Error(`${label} minimum cannot exceed maximum.`);\n }\n if (options.enumValues && reflected.name !== 'String') {\n throw new Error(`${label} enumValues require a string field.`);\n }\n }\n\n private itemSchema(item: DtoArrayItem, parents: Set<DtoClass>): ApiJsonSchema {\n if (typeof item !== 'string') return this.buildAt(item, parents);\n return new ApiJsonSchema(item === 'integer' ? 'integer' : item);\n }\n\n private validateAt(\n dtoClass: DtoClass,\n value: DtoValue,\n path: string,\n ): DtoValidationFailure | undefined {\n this.requireDto(dtoClass);\n if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n return new DtoValidationFailure(`${path} must be an object`);\n }\n const fields = this.fields(dtoClass);\n const known = new Set(fields.map((field: WpDtoFieldMetadata) => field.propertyKey));\n for (const key of Object.keys(value)) {\n if (!known.has(key)) return new DtoValidationFailure(`${path}.${key} is not allowed`);\n }\n for (const field of fields) {\n const fieldValue = Object.getOwnPropertyDescriptor(value, field.propertyKey)?.value;\n if (fieldValue === undefined) {\n if (field.options.required) {\n return new DtoValidationFailure(`${path}.${field.propertyKey} is required`);\n }\n continue;\n }\n const failure = this.validateField(dtoClass, field, fieldValue, `${path}.${field.propertyKey}`);\n if (failure) return failure;\n }\n return undefined;\n }\n\n private validateField(\n dtoClass: DtoClass,\n field: WpDtoFieldMetadata,\n value: DtoValue,\n path: string,\n ): DtoValidationFailure | undefined {\n // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token\n const reflected = Reflect.getMetadata(\n 'design:type',\n dtoClass.prototype,\n field.propertyKey,\n ) as DtoClass;\n const expected = reflected?.name;\n if (expected === 'Array') return this.validateArray(field.options, value, path);\n if (expected === 'String') {\n if (typeof value !== 'string') return new DtoValidationFailure(`${path} must be a string`);\n if (field.options.enumValues && !field.options.enumValues.includes(value)) {\n return new DtoValidationFailure(`${path} must be one of: ${field.options.enumValues.join(', ')}`);\n }\n return undefined;\n }\n if (expected === 'Number') {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n return new DtoValidationFailure(`${path} must be a number`);\n }\n if (field.options.integer && !Number.isInteger(value)) {\n return new DtoValidationFailure(`${path} must be an integer`);\n }\n if (field.options.minimum !== undefined && value < field.options.minimum) {\n return new DtoValidationFailure(`${path} must be >= ${field.options.minimum}`);\n }\n if (field.options.maximum !== undefined && value > field.options.maximum) {\n return new DtoValidationFailure(`${path} must be <= ${field.options.maximum}`);\n }\n return undefined;\n }\n if (expected === 'Boolean') {\n return typeof value === 'boolean'\n ? undefined\n : new DtoValidationFailure(`${path} must be a boolean`);\n }\n return this.validateAt(reflected, value, path);\n }\n\n private validateArray(\n options: WpDtoFieldOptions,\n value: DtoValue,\n path: string,\n ): DtoValidationFailure | undefined {\n if (!Array.isArray(value)) return new DtoValidationFailure(`${path} must be an array`);\n if (!options.arrayItems) return new DtoValidationFailure(`${path} has no item type`);\n for (let index = 0; index < value.length; index += 1) {\n const item = value[index];\n if (typeof options.arrayItems !== 'string') {\n const nested = this.validateAt(options.arrayItems, item, `${path}[${index}]`);\n if (nested) return nested;\n continue;\n }\n const wanted = options.arrayItems === 'integer' ? 'number' : options.arrayItems;\n if (typeof item !== wanted || (options.arrayItems === 'integer' && !Number.isInteger(item))) {\n return new DtoValidationFailure(`${path}[${index}] must be ${options.arrayItems}`);\n }\n }\n return undefined;\n }\n\n private fields(dtoClass: DtoClass): WpDtoFieldMetadata[] {\n const fields: Record<string, WpDtoFieldMetadata> =\n Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};\n return Object.values(fields);\n }\n\n private requireDto(dtoClass: DtoClass): void {\n if (!Reflect.getMetadata(DTO_MARKER, dtoClass)) {\n throw new Error(`${dtoClass.name} must be decorated with @WpDto() for schema generation.`);\n }\n }\n}\n"]}

package/src/mcp/McpCompileAssertions.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/src/mcp/McpCompileAssertions.js ADDED Viewed

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const McpMetadata_1 = require("./McpMetadata");
+const DtoSchema_1 = require("./DtoSchema");
+const invalidEmptyEnum = new DtoSchema_1.WpDtoFieldOptions('invalid enum', true, undefined, false, undefined, undefined,
+// @ts-expect-error enumValues must contain at least one allowed string
+[]);
+class InvalidMcpContract {
+    // @ts-expect-error read-only tools cannot also claim to be destructive
+    invalid() {
+        throw new Error('contract only');
+    }
+}
+tslib_1.__decorate([
+    (0, McpMetadata_1.WpMcpTool)({
+        name: 'invalid',
+        description: 'This declaration must never compile.',
+        readOnlyHint: true,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    }),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], InvalidMcpContract.prototype, "invalid", null);
+class InvalidMcpArities {
+    // @ts-expect-error MCP tools require exactly one request DTO
+    zero() {
+        throw new Error('contract only');
+    }
+    // @ts-expect-error MCP tools require exactly one request DTO
+    multi(_first, _second) {
+        throw new Error('contract only');
+    }
+}
+tslib_1.__decorate([
+    (0, McpMetadata_1.WpMcpTool)({
+        name: 'zero-arity',
+        description: 'This declaration must never compile.',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    }),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], InvalidMcpArities.prototype, "zero", null);
+tslib_1.__decorate([
+    (0, McpMetadata_1.WpMcpTool)({
+        name: 'multi-arity',
+        description: 'This declaration must never compile.',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    }),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Object, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], InvalidMcpArities.prototype, "multi", null);
+void InvalidMcpContract;
+void InvalidMcpArities;
+void invalidEmptyEnum;
+//# sourceMappingURL=McpCompileAssertions.js.map

package/src/mcp/McpCompileAssertions.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"McpCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,+CAA0C;AAC1C,2CAAgD;AAEhD,MAAM,gBAAgB,GAAG,IAAI,6BAAiB,CAC1C,cAAc,EACd,IAAI,EACJ,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS;AACT,uEAAuE;AACvE,EAAE,CACL,CAAC;AAEF,MAAe,kBAAkB;IAC7B,uEAAuE;IASvE,OAAO;QACH,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAHG;IARC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,IAAI;QACrB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;iDAGD;AAGL,MAAe,iBAAiB;IAC5B,6DAA6D;IAQ7D,IAAI;QACA,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IAED,6DAA6D;IAQ7D,KAAK,CAAC,MAAc,EAAE,OAAe;QACjC,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAfG;IAPC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;6CAGD;AAUD;IAPC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;8CAGD;AAGL,KAAK,kBAAkB,CAAC;AACxB,KAAK,iBAAiB,CAAC;AACvB,KAAK,gBAAgB,CAAC","sourcesContent":["import { WpMcpTool } from './McpMetadata';\nimport { WpDtoFieldOptions } from './DtoSchema';\n\nconst invalidEmptyEnum = new WpDtoFieldOptions(\n 'invalid enum',\n true,\n undefined,\n false,\n undefined,\n undefined,\n // @ts-expect-error enumValues must contain at least one allowed string\n [],\n);\n\nabstract class InvalidMcpContract {\n // @ts-expect-error read-only tools cannot also claim to be destructive\n @WpMcpTool({\n name: 'invalid',\n description: 'This declaration must never compile.',\n readOnlyHint: true,\n destructiveHint: true,\n idempotentHint: true,\n openWorldHint: false,\n })\n invalid(): Promise<void> {\n throw new Error('contract only');\n }\n}\n\nabstract class InvalidMcpArities {\n // @ts-expect-error MCP tools require exactly one request DTO\n @WpMcpTool({\n name: 'zero-arity',\n description: 'This declaration must never compile.',\n readOnlyHint: true,\n idempotentHint: true,\n openWorldHint: false,\n })\n zero(): Promise<object> {\n throw new Error('contract only');\n }\n\n // @ts-expect-error MCP tools require exactly one request DTO\n @WpMcpTool({\n name: 'multi-arity',\n description: 'This declaration must never compile.',\n readOnlyHint: true,\n idempotentHint: true,\n openWorldHint: false,\n })\n multi(_first: object, _second: object): Promise<object> {\n throw new Error('contract only');\n }\n}\n\nvoid InvalidMcpContract;\nvoid InvalidMcpArities;\nvoid invalidEmptyEnum;\n"]}

package/src/mcp/McpMetadata.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+import 'reflect-metadata';
+/** The immutable hints MCP clients use when deciding whether and how to call a tool. */
+export declare class WpMcpToolHints {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
+    readonly idempotentHint: boolean;
+    readonly openWorldHint: boolean;
+    constructor(readOnlyHint: boolean, destructiveHint: boolean, idempotentHint: boolean, openWorldHint: boolean);
+}
+type CommonToolOptions = {
+    /** Stable protocol name. Renaming this breaks saved agent workflows. */
+    name: string;
+    /** Tool-level documentation published verbatim by tools/list. */
+    description: string;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+type ReadOnlyToolOptions = CommonToolOptions & {
+    readOnlyHint: true;
+    destructiveHint?: never;
+};
+type MutatingToolOptions = CommonToolOptions & {
+    readOnlyHint: false;
+    destructiveHint: boolean;
+};
+/** Compiler-enforced exposure: a read-only tool cannot also claim to be destructive. */
+export type WpMcpToolOptions = ReadOnlyToolOptions | MutatingToolOptions;
+type AsyncObjectMethod = (...args: never[]) => Promise<object>;
+type ExactOneParameter<TMethod extends AsyncObjectMethod> = Parameters<TMethod>['length'] extends 1 ? object : never;
+type ExactOneMethodDescriptor<TMethod extends AsyncObjectMethod> = TypedPropertyDescriptor<TMethod> & ExactOneParameter<TMethod>;
+/** Method decorator restricted to one request DTO and one async response DTO. */
+export type WpMcpMethodDecorator = <TMethod extends AsyncObjectMethod>(target: object, propertyKey: string | symbol, descriptor: ExactOneMethodDescriptor<TMethod>) => void;
+/** Runtime metadata for one explicitly exposed endpoint. */
+export declare class WpMcpToolMetadata {
+    readonly methodName: string;
+    readonly name: string;
+    readonly description: string;
+    readonly hints: WpMcpToolHints;
+    constructor(methodName: string, name: string, description: string, hints: WpMcpToolHints);
+}
+/**
+ * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.
+ *
+ * This annotation owns tool-level documentation only. Input/output field documentation and JSON
+ * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains
+ * the sole runtime authorization policy.
+ */
+export declare function WpMcpTool(options: WpMcpToolOptions): WpMcpMethodDecorator;
+/** Returns only methods explicitly opted in through {@link WpMcpTool}. */
+export declare function getWpMcpTools(apiClass: Function): WpMcpToolMetadata[];
+export {};

package/src/mcp/McpMetadata.js ADDED Viewed

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpMcpToolMetadata = exports.WpMcpToolHints = void 0;
+exports.WpMcpTool = WpMcpTool;
+exports.getWpMcpTools = getWpMcpTools;
+require("reflect-metadata");
+const decorators_1 = require("../http/decorators");
+/** The immutable hints MCP clients use when deciding whether and how to call a tool. */
+class WpMcpToolHints {
+    readOnlyHint;
+    destructiveHint;
+    idempotentHint;
+    openWorldHint;
+    constructor(readOnlyHint, destructiveHint, idempotentHint, openWorldHint) {
+        this.readOnlyHint = readOnlyHint;
+        this.destructiveHint = destructiveHint;
+        this.idempotentHint = idempotentHint;
+        this.openWorldHint = openWorldHint;
+    }
+}
+exports.WpMcpToolHints = WpMcpToolHints;
+/** Runtime metadata for one explicitly exposed endpoint. */
+class WpMcpToolMetadata {
+    methodName;
+    name;
+    description;
+    hints;
+    constructor(methodName, name, description, hints) {
+        this.methodName = methodName;
+        this.name = name;
+        this.description = description;
+        this.hints = hints;
+    }
+}
+exports.WpMcpToolMetadata = WpMcpToolMetadata;
+/**
+ * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.
+ *
+ * This annotation owns tool-level documentation only. Input/output field documentation and JSON
+ * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains
+ * the sole runtime authorization policy.
+ */
+// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
+function WpMcpTool(options) {
+    if (options.name.trim() === '')
+        throw new Error('@WpMcpTool requires a non-empty stable name.');
+    if (options.description.trim() === '') {
+        throw new Error('@WpMcpTool requires non-empty tool documentation.');
+    }
+    return (target, propertyKey, _descriptor) => {
+        const apiClass = target.constructor;
+        const tools = Reflect.getMetadata(decorators_1.METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};
+        const methodName = String(propertyKey);
+        tools[methodName] = new WpMcpToolMetadata(methodName, options.name, options.description, new WpMcpToolHints(options.readOnlyHint, options.readOnlyHint ? false : options.destructiveHint, options.idempotentHint, options.openWorldHint));
+        Reflect.defineMetadata(decorators_1.METADATA_KEYS.MCP_TOOLS, tools, apiClass);
+    };
+}
+/** Returns only methods explicitly opted in through {@link WpMcpTool}. */
+// webpieces-disable no-function-outside-class -- metadata reader paired with the decorator
+function getWpMcpTools(apiClass) {
+    const tools = Reflect.getMetadata(decorators_1.METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};
+    return Object.values(tools);
+}
+//# sourceMappingURL=McpMetadata.js.map

package/src/mcp/McpMetadata.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"McpMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpMetadata.ts"],"names":[],"mappings":";;;AAmEA,8BA2BC;AAID,sCAIC;AAtGD,4BAA0B;AAC1B,mDAAmD;AAEnD,wFAAwF;AACxF,MAAa,cAAc;IAEH;IACA;IACA;IACA;IAJpB,YACoB,YAAqB,EACrB,eAAwB,EACxB,cAAuB,EACvB,aAAsB;QAHtB,iBAAY,GAAZ,YAAY,CAAS;QACrB,oBAAe,GAAf,eAAe,CAAS;QACxB,mBAAc,GAAd,cAAc,CAAS;QACvB,kBAAa,GAAb,aAAa,CAAS;IACvC,CAAC;CACP;AAPD,wCAOC;AAsCD,4DAA4D;AAC5D,MAAa,iBAAiB;IAEN;IACA;IACA;IACA;IAJpB,YACoB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,KAAqB;QAHrB,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,UAAK,GAAL,KAAK,CAAgB;IACtC,CAAC;CACP;AAPD,8CAOC;AAED;;;;;;GAMG;AACH,iGAAiG;AACjG,SAAgB,SAAS,CAAC,OAAyB;IAC/C,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAChG,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CACH,MAAc,EACd,WAA4B,EAC5B,WAA8C,EAC1C,EAAE;QACN,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;QACpC,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACjE,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACvC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,iBAAiB,CACrC,UAAU,EACV,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,WAAW,EACnB,IAAI,cAAc,CACd,OAAO,CAAC,YAAY,EACpB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EACtD,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,aAAa,CACxB,CACJ,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,0BAAa,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC,CAAC;AACN,CAAC;AAED,0EAA0E;AAC1E,2FAA2F;AAC3F,SAAgB,aAAa,CAAC,QAAkB;IAC5C,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACjE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { METADATA_KEYS } from '../http/decorators';\n\n/** The immutable hints MCP clients use when deciding whether and how to call a tool. */\nexport class WpMcpToolHints {\n constructor(\n public readonly readOnlyHint: boolean,\n public readonly destructiveHint: boolean,\n public readonly idempotentHint: boolean,\n public readonly openWorldHint: boolean,\n ) {}\n}\n\ntype CommonToolOptions = {\n /** Stable protocol name. Renaming this breaks saved agent workflows. */\n name: string;\n /** Tool-level documentation published verbatim by tools/list. */\n description: string;\n idempotentHint: boolean;\n openWorldHint: boolean;\n};\n\ntype ReadOnlyToolOptions = CommonToolOptions & {\n readOnlyHint: true;\n destructiveHint?: never;\n};\n\ntype MutatingToolOptions = CommonToolOptions & {\n readOnlyHint: false;\n destructiveHint: boolean;\n};\n\n/** Compiler-enforced exposure: a read-only tool cannot also claim to be destructive. */\nexport type WpMcpToolOptions = ReadOnlyToolOptions | MutatingToolOptions;\n\ntype AsyncObjectMethod = (...args: never[]) => Promise<object>;\ntype ExactOneParameter<TMethod extends AsyncObjectMethod> = Parameters<TMethod>['length'] extends 1\n ? object\n : never;\ntype ExactOneMethodDescriptor<TMethod extends AsyncObjectMethod> = TypedPropertyDescriptor<TMethod> &\n ExactOneParameter<TMethod>;\n\n/** Method decorator restricted to one request DTO and one async response DTO. */\nexport type WpMcpMethodDecorator = <TMethod extends AsyncObjectMethod>(\n target: object,\n propertyKey: string | symbol,\n descriptor: ExactOneMethodDescriptor<TMethod>,\n) => void;\n\n/** Runtime metadata for one explicitly exposed endpoint. */\nexport class WpMcpToolMetadata {\n constructor(\n public readonly methodName: string,\n public readonly name: string,\n public readonly description: string,\n public readonly hints: WpMcpToolHints,\n ) {}\n}\n\n/**\n * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.\n *\n * This annotation owns tool-level documentation only. Input/output field documentation and JSON\n * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains\n * the sole runtime authorization policy.\n */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpMcpTool(options: WpMcpToolOptions): WpMcpMethodDecorator {\n if (options.name.trim() === '') throw new Error('@WpMcpTool requires a non-empty stable name.');\n if (options.description.trim() === '') {\n throw new Error('@WpMcpTool requires non-empty tool documentation.');\n }\n return <TMethod extends AsyncObjectMethod>(\n target: object,\n propertyKey: string | symbol,\n _descriptor: ExactOneMethodDescriptor<TMethod>,\n ): void => {\n const apiClass = target.constructor;\n const tools: Record<string, WpMcpToolMetadata> =\n Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n const methodName = String(propertyKey);\n tools[methodName] = new WpMcpToolMetadata(\n methodName,\n options.name,\n options.description,\n new WpMcpToolHints(\n options.readOnlyHint,\n options.readOnlyHint ? false : options.destructiveHint,\n options.idempotentHint,\n options.openWorldHint,\n ),\n );\n Reflect.defineMetadata(METADATA_KEYS.MCP_TOOLS, tools, apiClass);\n };\n}\n\n/** Returns only methods explicitly opted in through {@link WpMcpTool}. */\n// webpieces-disable no-function-outside-class -- metadata reader paired with the decorator\nexport function getWpMcpTools(apiClass: Function): WpMcpToolMetadata[] {\n const tools: Record<string, WpMcpToolMetadata> =\n Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n return Object.values(tools);\n}\n"]}