@lerianstudio/matcher-mcp 1.0.0-beta.5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,281 @@
+# matcher-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
+operator drive the [Matcher](../) reconciliation engine through MCP tools.
+
+## What this is
+
+A **stateless credential relay**. On every inbound MCP connection it reads the
+operator's `Authorization: Bearer <matcher-jwt>` header and forwards it verbatim
+to the Matcher API, exposing the reconciliation surface as MCP tools. It holds
+**no credentials** and performs **no token validation** — Matcher and plugin-auth
+own that (Matcher itself does no local signature/`exp`/`nbf` checks either; it
+delegates to plugin-auth). The server keeps no per-connection session state: a
+fresh in-memory server is built per request, so it can be scaled or restarted
+freely.
+
+Tenant identity derives **entirely from the token**. The MCP server never
+accepts, injects, or infers a `tenant_id` / `tenantId` / `tenant` parameter on
+any tool, and Matcher resolves the tenant from the relayed JWT.
+
+## Auth model
+
+The operator's MCP client supplies the matcher bearer token as an
+`Authorization: Bearer <matcher-jwt>` header on the connection. The server:
+
+- forwards that header **verbatim** to the Matcher API on every tool call;
+- **never logs, stores, or persists** the token;
+- **never places it** in errors, tool output, spans, span attributes, span
+  events, or metrics.
+
+The relay is **fail-closed**: a tool call with no relayed bearer credential is
+rejected with operator-remediation text and makes **no** call to Matcher — it
+never falls back to an unauthenticated or default-tenant request. Use the
+`mcp_whoami` tool to confirm your client is sending the header; it reports
+presence only and never echoes the token value.
+
+## Deployment
+
+The server ships as the segregated **`matcher-mcp`** Docker image — a distroless
+Node service built by [`.github/workflows/build-mcp.yml`](../.github/workflows/build-mcp.yml)
+and published to GHCR. The image rides the same `v<version>` semantic-release tag
+as the matcher app, which also pins the embedded OpenAPI spec to the matched
+matcher version. The bearer token the relay forwards is never baked into the
+image.
+
+It speaks **Streamable HTTP** and binds `MCP_PORT` (default `4019`), exposing two
+endpoints:
+
+| Method | Path       | Purpose                                          |
+|--------|------------|--------------------------------------------------|
+| `GET`  | `/healthz` | Plain liveness probe.                            |
+| `POST` | `/mcp`     | The Streamable HTTP MCP endpoint clients connect to. |
+
+Point any Streamable-HTTP MCP client at `POST /mcp` and send the matcher bearer
+token as the `Authorization` header.
+
+## Installing in an MCP client
+
+The server speaks **Streamable HTTP**, so you connect a client to its `POST /mcp`
+endpoint over the network and send your matcher JWT as
+`Authorization: Bearer <token>`. There is **no stdio transport** — the usual
+`command: npx …` MCP wiring does not apply here; every client below is configured
+as a *remote / HTTP* server.
+
+### 1. Get an endpoint
+
+Two options for `<mcp-url>`:
+
+- **Connect to a deployed server (recommended).** Point your client at a running
+  `matcher-mcp` (the GHCR image), e.g. `https://matcher-mcp.example.com/mcp`.
+- **Run it locally with `npx`.** `@lerianstudio/matcher-mcp` is a **public**
+  package (Apache-2.0) — no registry auth needed. Start the relay (binds `:4019`)
+  pointed at your Matcher API:
+
+  ```bash
+  MATCHER_API_URL=https://your-matcher-api npx @lerianstudio/matcher-mcp
+  ```
+
+  then use `http://localhost:4019/mcp` as `<mcp-url>`.
+
+### 2. The token
+
+Every client sends the **matcher JWT** as `Authorization: Bearer <matcher-jwt>`
+on the MCP connection. The relay forwards it verbatim to the Matcher API; tenant
+and identity derive entirely from it. Get it from your Access Manager /
+plugin-auth — the same token you'd use against the Matcher API directly. The
+relay holds no credentials of its own.
+
+Replace `<matcher-jwt>` and `<mcp-url>` below accordingly.
+
+### 3. Wire it into your client
+
+**Claude Code** — CLI:
+
+```bash
+claude mcp add --transport http matcher <mcp-url> \
+  --header "Authorization: Bearer <matcher-jwt>"
+```
+
+or `.mcp.json` (`${MATCHER_JWT}` is read from the environment at connect time):
+
+```json
+{
+  "mcpServers": {
+    "matcher": {
+      "type": "http",
+      "url": "<mcp-url>",
+      "headers": { "Authorization": "Bearer ${MATCHER_JWT}" }
+    }
+  }
+}
+```
+
+**opencode** — `opencode.json` (`{env:VAR}` reads from the environment):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "matcher": {
+      "type": "remote",
+      "url": "<mcp-url>",
+      "enabled": true,
+      "headers": { "Authorization": "Bearer {env:MATCHER_JWT}" }
+    }
+  }
+}
+```
+
+**droid (Factory)** — CLI:
+
+```bash
+droid mcp add matcher <mcp-url> --type http \
+  --header "Authorization: Bearer <matcher-jwt>"
+```
+
+or `~/.factory/mcp.json` (user-level) / `.factory/mcp.json` (project-level):
+
+```json
+{
+  "mcpServers": {
+    "matcher": {
+      "type": "http",
+      "url": "<mcp-url>",
+      "headers": { "Authorization": "Bearer <matcher-jwt>" }
+    }
+  }
+}
+```
+
+**pi (Pi coding agent)** — Streamable HTTP support comes from the
+[`pi-mcp`](https://github.com/eliemessiecode/pi-mcp) extension. From inside pi:
+
+```
+/mcp add matcher <mcp-url> Authorization=Bearer <matcher-jwt>
+```
+
+Servers are stored in `~/.pi/agent/mcp/servers.json` (global) or
+`.pi/mcp/servers.json` (project-level).
+
+### 4. Verify the connection
+
+Once connected, call the `mcp_whoami` tool. It reports **only** whether the
+bearer header arrived (never echoing the token), so a `present: true` confirms
+your client is sending `Authorization` correctly. A tool that returns "No matcher
+credential" means the header is not reaching the server — re-check the `headers`
+block above.
+
+> Any Streamable-HTTP MCP client works the same way: point it at `<mcp-url>` and
+> send `Authorization: Bearer <matcher-jwt>`. The four above are just the common
+> ones; the pattern is identical everywhere.
+
+## Configuration
+
+All configuration is read once from the environment at boot and frozen. An
+explicitly-set but invalid value fails loudly at boot rather than silently
+degrading to a default. Env names mirror the matcher Go service.
+
+| Variable                      | Default                 | Purpose |
+|-------------------------------|-------------------------|---------|
+| `MCP_PORT`                    | `4019`                  | Port the Streamable HTTP server binds (4018 is matcher, so this avoids a dev collision). |
+| `MATCHER_API_URL`             | `http://localhost:4018` | Base URL of the Matcher API the tools relay to (single source of truth for every tool). Trailing slashes are trimmed. |
+| `MATCHER_TIMEOUT_MS`          | `30000`                 | Per-request timeout the matcher HTTP client enforces via `AbortController`, matching matcher's 30s transaction timeout. |
+| `MAX_BODY_BYTES`              | `1048576` (1 MiB)       | Maximum accepted inbound request body size; the transport rejects an over-limit body with `413` before parsing, so an unbounded read cannot exhaust memory. |
+| `ENABLE_TELEMETRY`            | `false`                 | Whether OpenTelemetry traces + metrics are exported. **Off** by default. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | _(SDK default)_         | OTLP HTTP endpoint traces + metrics export to when telemetry is enabled. When unset, the OTel SDK falls back to its own default (`localhost:4318`). |
+| `OTEL_RESOURCE_SERVICE_NAME`  | `matcher-mcp`           | `service.name` stamped on exported telemetry, so the relay's signals are distinguishable from matcher's own in a shared collector. |
+
+Telemetry is a **complete no-op** when `ENABLE_TELEMETRY` is false: no SDK is
+initialized, no exporters are created, and no network calls are made, so dev,
+test, and single-operator runs pay nothing. Whether telemetry is enabled or not,
+spans and metrics record **only** the tool name and call outcome (plus the
+matcher HTTP status on failure) — never tool arguments, headers, tenant
+identifiers, or the token.
+
+## Tool catalog
+
+The server exposes a **curated** typed surface (one ergonomic tool per common
+operation, with validated arguments) plus a **generic** escape hatch over the
+full embedded OpenAPI spec.
+
+### Curated families
+
+| Family         | Purpose |
+|----------------|---------|
+| `fee_schedule_*` | Manage fee schedules — create, list, get, update, delete, and simulate. |
+| `fee_rule_*`     | Manage fee rules attached to schedules — create, list, get, update, delete. |
+| `match_rule_*`   | Manage a context's match rules — create, list, get, update, delete, reorder. |
+| `context_*`      | Manage reconciliation contexts — create, list, get, update, delete. |
+| `source_*`       | Manage a context's data sources — create, list, get, update, delete. |
+| `match_run_*`    | Drive reconciliation runs — start a run, list runs, get a run, inspect match groups. |
+| `exception_*`    | Work reconciliation exceptions — list/get, history and comments (list/add/delete), per-exception action verbs (dispatch, open-dispute, force-match, adjust-entry), and cross-exception bulk actions (assign/resolve/dispatch). |
+| `dispute_*`      | Manage the dispute lifecycle — list, get, close, submit evidence. |
+| `ingestion_*`    | Inspect a context's import lifecycle — list jobs, get a job, list a job's per-row errors and transactions, search transactions, ignore a transaction. |
+| `dashboard_*`    | Read a context's reporting dashboard — combined aggregates plus focused slices (cash-impact, match-rate, metrics, SLA, source-breakdown, volume). |
+| `report_*`       | Pull a context's reports — paginated matched/unmatched/variance reads, the summary read, four counts (exceptions/matched/unmatched/transactions), and five base64 exports (exceptions/matched/summary/unmatched/variance). |
+
+### Generic trio
+
+| Tool                         | Purpose |
+|------------------------------|---------|
+| `matcher_list_operations`    | List every operation in the embedded OpenAPI spec. |
+| `matcher_describe_operation` | Describe one operation — its parameters, request body schema, and responses. |
+| `matcher_invoke`             | Assemble, validate, and dispatch any operation in the spec with the relayed token. |
+
+The curated tools and `matcher_invoke` are two front doors onto a single matcher
+HTTP client and a single token relay, so both surfaces map matcher errors
+([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem+json) identically.
+
+### Intentionally not curated
+
+Multipart **file upload** (`uploadFile`) and **document extraction**
+(`extractDocument`) carry a `multipart/form-data` binary body that a JSON tool
+cannot express, and the inbound **webhook receiver** (`processCallback`) is an
+inbound endpoint, not an operator action. These are deliberately left off the
+curated surface and remain reachable only via `matcher_invoke`.
+
+## Project layout
+
+This is a **standalone pnpm project** with its own lockfile — not a workspace
+member, mirroring the `ui/` precedent. It shares no dependency tree with the Go
+module at the repo root.
+
+```
+mcp/
+├── package.json        # pnpm@11.5.2, Node >=22
+├── tsconfig.json       # strict, NodeNext (matches the MCP SDK's ESM packaging)
+├── eslint.config.js    # flat config, mirrors ui/
+├── vitest.config.ts
+└── src/
+    ├── server.ts       # entry point: builds the per-request server, wires tools + telemetry
+    ├── config.ts       # frozen, fail-loud bootstrap config
+    ├── transport/      # Streamable HTTP transport (GET /healthz + POST /mcp)
+    ├── auth/           # request-scoped fail-closed bearer-token relay
+    ├── matcher/        # Matcher HTTP client
+    ├── observability/  # OpenTelemetry init + token-free tool instrumentation
+    ├── spec/           # embedded OpenAPI spec + operation index
+    └── tools/          # curated families + the generic trio
+```
+
+## Development
+
+Run all scripts from this directory (or with `pnpm -C mcp <script>`):
+
+```bash
+pnpm install     # install deps (own lockfile)
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint
+pnpm build       # type-check + emit to dist/
+pnpm test        # run vitest
+pnpm dev         # run with --watch
+```
+
+## Toolchain
+
+Mirrors the `ui/` sub-project: **pnpm** (`pnpm@11.5.2`), Node `>=22`, ESLint flat
+config (`@eslint/js` + `typescript-eslint`), and Vitest. There is no Prettier —
+`ui/` does not use one, so neither does this project.
+
+Build uses `tsc` (this is a Node service, not a browser bundle), which is the one
+deliberate divergence from `ui/`'s Vite build.

package/dist/auth/request-token.js

@@ -0,0 +1,117 @@
+// Request-scoped bearer-token relay — the security spine.
+//
+// Every tool that touches matcher data must use the *inbound caller's* bearer
+// token, resolved per request, and fail closed when it is absent. This module
+// owns that contract:
+//
+//   - `runWithBearerToken(token, fn)` seeds an AsyncLocalStorage store at the
+//     HTTP boundary (transport/http.ts) so handlers can recover the token even
+//     when the SDK does not thread request headers through `extra`.
+//   - `getRequestBearerToken(extra?)` returns the current caller's token,
+//     preferring the SDK-native `extra.requestInfo.headers.authorization` when
+//     present and falling back to the ALS store seeded at the boundary.
+//   - `requireMatcherClient(extra?)` is the single chokepoint tools call: it
+//     reads the token, throws `UnauthenticatedError` when it is missing / empty
+//     / not a Bearer credential, and otherwise builds a per-request
+//     `MatcherClient` from it.
+//
+// Security invariants (asserted by tests):
+//   - The token is NEVER logged and NEVER placed in an error message.
+//   - No tenant identifier is read or injected anywhere — tenant identity
+//     derives solely from the relayed JWT (matcher + plugin-auth own it).
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { loadConfig } from '../config.js';
+import { createMatcherClient } from '../matcher/client.js';
+const authStorage = new AsyncLocalStorage();
+/**
+ * Operator-facing remediation text shown when the caller did not relay a usable
+ * bearer token. It deliberately contains no token material and no internal
+ * detail — just what the operator must do to fix their connection.
+ */
+export const UNAUTHENTICATED_REMEDIATION = 'No matcher credential was provided. Configure your MCP client to send an ' +
+    '`Authorization: Bearer <your-matcher-jwt>` header on each request, then ' +
+    'retry. This server holds no credentials of its own and relays yours verbatim.';
+/**
+ * Thrown when a tool requires the caller's matcher credential but none was
+ * relayed (missing, empty, or not a Bearer credential). Carries only the
+ * operator remediation text — never any token material.
+ */
+export class UnauthenticatedError extends Error {
+    constructor(message = UNAUTHENTICATED_REMEDIATION) {
+        super(message);
+        this.name = 'UnauthenticatedError';
+    }
+}
+/** Run `fn` with the given raw `Authorization` header bound to this async context. */
+export function runWithBearerToken(authorization, fn) {
+    return authStorage.run({ authorization }, fn);
+}
+/**
+ * Pull the raw `Authorization` header value out of an SDK `extra`, if it carries
+ * request headers. Header names are case-insensitive; a multi-value header is
+ * not expected for `Authorization`, so we take the first element when an array.
+ */
+function authorizationFromExtra(extra) {
+    const headers = extra?.requestInfo?.headers;
+    if (!headers) {
+        return undefined;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === 'authorization') {
+            return Array.isArray(value) ? value[0] : value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse a Bearer token out of a raw `Authorization` header value.
+ * Returns the token when the header is the `Bearer <token>` scheme with a
+ * non-empty token; returns `undefined` for any other shape (missing, empty,
+ * wrong scheme). The scheme match is case-insensitive per RFC 7235.
+ */
+function parseBearer(authorization) {
+    if (!authorization) {
+        return undefined;
+    }
+    const match = /^Bearer[ \t]+(.+)$/i.exec(authorization.trim());
+    if (!match) {
+        return undefined;
+    }
+    const token = match[1]?.trim();
+    return token && token.length > 0 ? token : undefined;
+}
+/**
+ * Resolve the current caller's bearer token, request-scoped.
+ *
+ * Resolution order:
+ *   1. SDK-native `extra.requestInfo.headers.authorization`, when the handler
+ *      was given an `extra` carrying request headers.
+ *   2. The ALS store seeded by `runWithBearerToken` at the HTTP boundary.
+ *
+ * Returns `undefined` when no usable Bearer credential is present (missing,
+ * empty, or non-Bearer scheme) — callers fail closed on that.
+ */
+export function getRequestBearerToken(extra) {
+    const fromExtra = parseBearer(authorizationFromExtra(extra));
+    if (fromExtra) {
+        return fromExtra;
+    }
+    return parseBearer(authStorage.getStore()?.authorization);
+}
+/**
+ * The single chokepoint every matcher-touching tool calls. Reads the caller's
+ * request-scoped token and, when present, returns a `MatcherClient` bound to it.
+ * Fails closed with `UnauthenticatedError` when the token is absent / empty /
+ * not a Bearer credential.
+ *
+ * `config` is injectable for tests; production callers pass nothing and get the
+ * process config.
+ */
+export function requireMatcherClient(extra, config = loadConfig()) {
+    const token = getRequestBearerToken(extra);
+    if (!token) {
+        throw new UnauthenticatedError();
+    }
+    return createMatcherClient(config.matcherApiUrl, token);
+}
+//# sourceMappingURL=request-token.js.map

package/dist/auth/request-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-token.js","sourceRoot":"","sources":["../../src/auth/request-token.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,sBAAsB;AACtB,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,oEAAoE;AACpE,0EAA0E;AAC1E,+EAA+E;AAC/E,wEAAwE;AACxE,6EAA6E;AAC7E,gFAAgF;AAChF,oEAAoE;AACpE,+BAA+B;AAC/B,EAAE;AACF,2CAA2C;AAC3C,sEAAsE;AACtE,0EAA0E;AAC1E,0EAA0E;AAE1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAe,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAA;AAQ9E,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAoB,CAAA;AAE7D;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GACtC,2EAA2E;IAC3E,0EAA0E;IAC1E,+EAA+E,CAAA;AAEjF;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,UAAkB,2BAA2B;QACvD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF;AAaD,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAChC,aAAiC,EACjC,EAAW;IAEX,OAAO,WAAW,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAA;AAC/C,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB,CAAC,KAAmC;IACjE,MAAM,OAAO,GAAG,KAAK,EAAE,WAAW,EAAE,OAAO,CAAA;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,eAAe,EAAE,CAAC;YAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;QAChD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,aAAiC;IACpD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAA;IAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;IAC9B,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACtD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAwB;IAC5D,MAAM,SAAS,GAAG,WAAW,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAA;IAC5D,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,WAAW,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAwB,EACxB,SAAiB,UAAU,EAAE;IAE7B,MAAM,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,oBAAoB,EAAE,CAAA;IAClC,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;AACzD,CAAC"}