@pithy-sh/auth 0.11.0 → 0.12.0
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.
- package/README.md +30 -2
- package/dist/audit/actions.d.ts +39 -0
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +40 -1
- package/dist/audit/emit.d.ts +34 -0
- package/dist/audit/emit.d.ts.map +1 -1
- package/dist/audit/emit.js +47 -1
- package/dist/audit/evidence.d.ts +8 -2
- package/dist/audit/evidence.d.ts.map +1 -1
- package/dist/capability.d.ts +31 -11
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +38 -5
- package/dist/client/api.d.ts +55 -12
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +57 -18
- package/dist/client/bearer.d.ts +110 -0
- package/dist/client/bearer.d.ts.map +1 -0
- package/dist/client/bearer.js +265 -0
- package/dist/client/handoff.d.ts +77 -0
- package/dist/client/handoff.d.ts.map +1 -0
- package/dist/client/handoff.js +119 -0
- package/dist/client/mcp.d.ts +70 -0
- package/dist/client/mcp.d.ts.map +1 -0
- package/dist/client/mcp.js +65 -0
- package/dist/data/betterAuth.d.ts +3 -2
- package/dist/data/betterAuth.d.ts.map +1 -1
- package/dist/data/betterAuth.js +5 -3
- package/dist/data/kitFields.d.ts +5 -0
- package/dist/data/kitFields.d.ts.map +1 -1
- package/dist/data/kitFields.js +5 -0
- package/dist/data/tables.d.ts +25 -4
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -3
- package/dist/data/userLifecycle.d.ts +9 -0
- package/dist/data/userLifecycle.d.ts.map +1 -1
- package/dist/data/userLifecycle.js +6 -2
- package/dist/data/verificationOutcome.d.ts +53 -0
- package/dist/data/verificationOutcome.d.ts.map +1 -0
- package/dist/data/verificationOutcome.js +50 -0
- package/dist/email/send.js +6 -2
- package/dist/http/adminRoutes.d.ts.map +1 -1
- package/dist/http/adminRoutes.js +56 -10
- package/dist/http/csrf.d.ts.map +1 -1
- package/dist/http/csrf.js +2 -1
- package/dist/http/guards.d.ts +15 -11
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +46 -11
- package/dist/http/handoff.d.ts +76 -0
- package/dist/http/handoff.d.ts.map +1 -0
- package/dist/http/handoff.js +316 -0
- package/dist/http/middleware.d.ts +12 -0
- package/dist/http/middleware.d.ts.map +1 -1
- package/dist/http/middleware.js +25 -4
- package/dist/http/resolve.d.ts.map +1 -1
- package/dist/http/resolve.js +9 -3
- package/dist/http/responses.d.ts +142 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +66 -10
- package/dist/http/routes.d.ts +2 -0
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +35 -4
- package/dist/http/schemas.d.ts +57 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +44 -1
- package/dist/http/views.d.ts +22 -2
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +40 -4
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -2
- package/dist/instance/auth.d.ts +148 -10
- package/dist/instance/auth.d.ts.map +1 -1
- package/dist/instance/auth.js +86 -41
- package/dist/instance/plugins.d.ts +6 -0
- package/dist/instance/plugins.d.ts.map +1 -1
- package/dist/instance/plugins.js +14 -1
- package/dist/ledger/read.d.ts +53 -0
- package/dist/ledger/read.d.ts.map +1 -0
- package/dist/ledger/read.js +85 -0
- package/dist/ledger/record.d.ts +35 -0
- package/dist/ledger/record.d.ts.map +1 -0
- package/dist/ledger/record.js +98 -0
- package/dist/lifecycle/erasure.d.ts +9 -0
- package/dist/lifecycle/erasure.d.ts.map +1 -0
- package/dist/lifecycle/erasure.js +96 -0
- package/dist/lifecycle/inactivity.d.ts +19 -0
- package/dist/lifecycle/inactivity.d.ts.map +1 -0
- package/dist/lifecycle/inactivity.js +28 -0
- package/dist/lifecycle/transitions.d.ts +22 -1
- package/dist/lifecycle/transitions.d.ts.map +1 -1
- package/dist/lifecycle/transitions.js +51 -4
- package/dist/mcp/argumentClass.d.ts +51 -0
- package/dist/mcp/argumentClass.d.ts.map +1 -0
- package/dist/mcp/argumentClass.js +69 -0
- package/dist/mcp/capability.d.ts +50 -0
- package/dist/mcp/capability.d.ts.map +1 -0
- package/dist/mcp/capability.js +140 -0
- package/dist/mcp/clientMetadata.d.ts +40 -0
- package/dist/mcp/clientMetadata.d.ts.map +1 -0
- package/dist/mcp/clientMetadata.js +68 -0
- package/dist/mcp/consent.d.ts +49 -0
- package/dist/mcp/consent.d.ts.map +1 -0
- package/dist/mcp/consent.js +69 -0
- package/dist/mcp/dispatch.d.ts +35 -0
- package/dist/mcp/dispatch.d.ts.map +1 -0
- package/dist/mcp/dispatch.js +135 -0
- package/dist/mcp/floor.d.ts +37 -0
- package/dist/mcp/floor.d.ts.map +1 -0
- package/dist/mcp/floor.js +41 -0
- package/dist/mcp/host.d.ts +34 -0
- package/dist/mcp/host.d.ts.map +1 -0
- package/dist/mcp/host.js +2 -0
- package/dist/mcp/http/redirectList.d.ts +9 -0
- package/dist/mcp/http/redirectList.d.ts.map +1 -0
- package/dist/mcp/http/redirectList.js +24 -0
- package/dist/mcp/http/responses.d.ts +143 -0
- package/dist/mcp/http/responses.d.ts.map +1 -0
- package/dist/mcp/http/responses.js +83 -0
- package/dist/mcp/http/routes.d.ts +28 -0
- package/dist/mcp/http/routes.d.ts.map +1 -0
- package/dist/mcp/http/routes.js +517 -0
- package/dist/mcp/http/schemas.d.ts +24 -0
- package/dist/mcp/http/schemas.d.ts.map +1 -0
- package/dist/mcp/http/schemas.js +18 -0
- package/dist/mcp/marker.d.ts +15 -0
- package/dist/mcp/marker.d.ts.map +1 -0
- package/dist/mcp/marker.js +15 -0
- package/dist/mcp/provider.d.ts +78 -0
- package/dist/mcp/provider.d.ts.map +1 -0
- package/dist/mcp/provider.js +108 -0
- package/dist/mcp/purge.d.ts +15 -0
- package/dist/mcp/purge.d.ts.map +1 -0
- package/dist/mcp/purge.js +31 -0
- package/dist/mcp/rpc.d.ts +79 -0
- package/dist/mcp/rpc.d.ts.map +1 -0
- package/dist/mcp/rpc.js +103 -0
- package/dist/mcp/toolAudit.d.ts +76 -0
- package/dist/mcp/toolAudit.d.ts.map +1 -0
- package/dist/mcp/toolAudit.js +86 -0
- package/dist/migrations/0006_verification_outcomes.d.ts +15 -0
- package/dist/migrations/0006_verification_outcomes.d.ts.map +1 -0
- package/dist/migrations/0006_verification_outcomes.js +35 -0
- package/dist/migrations/0007_erasure_record.d.ts +17 -0
- package/dist/migrations/0007_erasure_record.d.ts.map +1 -0
- package/dist/migrations/0007_erasure_record.js +36 -0
- package/dist/migrations/0008_last_active.d.ts +15 -0
- package/dist/migrations/0008_last_active.d.ts.map +1 -0
- package/dist/migrations/0008_last_active.js +29 -0
- package/dist/migrations/set.d.ts +4 -1
- package/dist/migrations/set.d.ts.map +1 -1
- package/dist/migrations/set.js +8 -2
- package/dist/peer.d.ts +3 -2
- package/dist/peer.d.ts.map +1 -1
- package/dist/processing/activities.d.ts +6 -0
- package/dist/processing/activities.d.ts.map +1 -0
- package/dist/processing/activities.js +12 -0
- package/dist/purge/contribution.d.ts +20 -5
- package/dist/purge/contribution.d.ts.map +1 -1
- package/dist/purge/contribution.js +20 -6
- package/dist/purge/run.d.ts +75 -5
- package/dist/purge/run.d.ts.map +1 -1
- package/dist/purge/run.js +117 -14
- package/dist/purge/workflow.d.ts +15 -2
- package/dist/purge/workflow.d.ts.map +1 -1
- package/dist/purge/workflow.js +51 -7
- package/dist/test-utils/accountFootprint.d.ts +5 -2
- package/dist/test-utils/accountFootprint.d.ts.map +1 -1
- package/dist/test-utils/accountFootprint.js +7 -2
- package/dist/test-utils/liveApp.d.ts +6 -0
- package/dist/test-utils/liveApp.d.ts.map +1 -1
- package/dist/test-utils/liveApp.js +7 -2
- package/dist/token/handoff.d.ts +80 -0
- package/dist/token/handoff.d.ts.map +1 -0
- package/dist/token/handoff.js +136 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/docs/account-lifecycle.md +59 -7
- package/docs/apple-signin.md +32 -4
- package/docs/facebook-oauth.md +2 -2
- package/docs/github-oauth.md +2 -2
- package/docs/google-oauth.md +9 -7
- package/docs/microsoft-oauth.md +2 -2
- package/package.json +11 -5
- package/pithy.manifest.json +2 -2
- package/pithy.mcp.manifest.json +36 -0
- package/src/audit/actions.ts +39 -0
- package/src/audit/emit.ts +63 -0
- package/src/audit/evidence.ts +8 -4
- package/src/capability.ts +80 -23
- package/src/client/api.ts +69 -19
- package/src/client/bearer.ts +388 -0
- package/src/client/handoff.ts +172 -0
- package/src/client/mcp.ts +140 -0
- package/src/data/betterAuth.ts +8 -4
- package/src/data/kitFields.ts +2 -0
- package/src/data/tables.ts +4 -2
- package/src/data/userLifecycle.ts +15 -3
- package/src/data/verificationOutcome.ts +86 -0
- package/src/email/send.ts +2 -2
- package/src/http/adminRoutes.ts +68 -3
- package/src/http/csrf.ts +4 -1
- package/src/http/guards.ts +48 -11
- package/src/http/handoff.ts +350 -0
- package/src/http/middleware.ts +29 -3
- package/src/http/resolve.ts +25 -25
- package/src/http/responses.ts +134 -8
- package/src/http/routes.ts +63 -4
- package/src/http/schemas.ts +85 -0
- package/src/http/views.ts +46 -2
- package/src/index.ts +2 -0
- package/src/instance/auth.ts +51 -1
- package/src/instance/plugins.ts +20 -2
- package/src/ledger/read.ts +133 -0
- package/src/ledger/record.ts +198 -0
- package/src/lifecycle/erasure.ts +118 -0
- package/src/lifecycle/inactivity.ts +56 -0
- package/src/lifecycle/transitions.ts +75 -5
- package/src/mcp/argumentClass.ts +112 -0
- package/src/mcp/capability.ts +194 -0
- package/src/mcp/clientMetadata.ts +81 -0
- package/src/mcp/consent.ts +95 -0
- package/src/mcp/dispatch.ts +154 -0
- package/src/mcp/floor.ts +62 -0
- package/src/mcp/host.ts +36 -0
- package/src/mcp/http/redirectList.ts +26 -0
- package/src/mcp/http/responses.ts +157 -0
- package/src/mcp/http/routes.ts +635 -0
- package/src/mcp/http/schemas.ts +37 -0
- package/src/mcp/marker.ts +18 -0
- package/src/mcp/provider.ts +151 -0
- package/src/mcp/purge.ts +39 -0
- package/src/mcp/rpc.ts +135 -0
- package/src/mcp/toolAudit.ts +132 -0
- package/src/migrations/0006_verification_outcomes.ts +51 -0
- package/src/migrations/0007_erasure_record.ts +43 -0
- package/src/migrations/0008_last_active.ts +30 -0
- package/src/migrations/set.ts +7 -1
- package/src/processing/activities.ts +14 -0
- package/src/purge/contribution.ts +37 -10
- package/src/purge/run.ts +179 -16
- package/src/purge/workflow.ts +65 -7
- package/src/seeds/example.ts +2 -2
- package/src/test-utils/accountFootprint.ts +10 -1
- package/src/test-utils/liveApp.ts +10 -1
- package/src/token/handoff.ts +180 -0
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/mcp/provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,SAAS,QAAQ,CAAC;AAE/B,oGAAoG;AACpG,eAAO,MAAM,UAAU,mBAAe,gBAAgB,CAAU,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,eAAe;aAC1B,WAAW,EAAE,iBAAiB;aAC9B,aAAa,EAAE,mBAAmB;aAClC,mBAAmB,EAAE,yBAAyB;aAC9C,iBAAiB,EAAE,uBAAuB;aAC1C,gBAAgB,EAAE,sBAAsB;aACxC,YAAY,EAAE,kBAAkB;aAChC,oBAAoB,EAAE,0BAA0B;CACxC,CAAC;AAEX,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5D;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,kBAAkB,CAyBxF;AAED,gGAAgG;AAChG,MAAM,MAAM,kBAAkB,GAAG,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC"}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { APIError, createAuthMiddleware } from "better-auth/api";
|
|
4
|
+
import { oauthProvider } from "@better-auth/oauth-provider";
|
|
5
|
+
//#region src/mcp/provider.ts
|
|
6
|
+
/**
|
|
7
|
+
* The authorization server the MCP capability composes into the auth instance (`docs/AGENT-ACCESS.md` §4).
|
|
8
|
+
*
|
|
9
|
+
* **Composed, not written.** Better Auth's OAuth 2.1 provider turns the instance into an authorization server:
|
|
10
|
+
* dynamic client registration, PKCE, resource-bound JWT access tokens signed by the JWKS the `jwt` plugin already
|
|
11
|
+
* keeps, refresh tokens, and the RFC 8414 metadata a client discovers it by. Beside registration, this module plugs in
|
|
12
|
+
* the Client ID Metadata Document discovery from `@better-auth/cimd` (`./clientMetadata.ts`), so a client may also be
|
|
13
|
+
* known by the URL of a document it publishes. That one extension adds the registration path the MCP specification
|
|
14
|
+
* prefers; everything else this module adds is policy, and every line of that narrows the provider's defaults.
|
|
15
|
+
*
|
|
16
|
+
* **One scope, and it is not a permission.** The consent is informational (§4.3): one decision, *let this client
|
|
17
|
+
* act as you in this application*, so the token carries no permission selection. {@link MCP_SCOPE} is the only
|
|
18
|
+
* scope a client may hold beside `offline_access`, which buys a refresh token and nothing else. The role is the only
|
|
19
|
+
* authority over what a call may do, and the routes enforce it, so there is no scope vocabulary to ask for.
|
|
20
|
+
*
|
|
21
|
+
* **The token binds the resource and the user, and nothing else.** The one resource is this Worker's MCP endpoint,
|
|
22
|
+
* seeded as the provider's only resource and linked to every client at registration, so a token minted for it is a
|
|
23
|
+
* JWT whose `aud` is that URL and cannot be replayed at another. `sub` is the user and `sid` the session they
|
|
24
|
+
* consented in; the MCP endpoint refuses a token whose session has ended.
|
|
25
|
+
*
|
|
26
|
+
* **No client credentials grant.** A token here acts *as somebody*; a machine-to-machine token acts as nobody, which
|
|
27
|
+
* is the control-plane seam's job (§1), not this one's.
|
|
28
|
+
*
|
|
29
|
+
* **The consent screen every time.** The provider skips consent for a client that already holds it; this kit asks
|
|
30
|
+
* again, so a client asking for access again is a new decision the user can see, and an audited one. A client asking
|
|
31
|
+
* to be shown nothing (`prompt=none`) is refused with `consent_required` before the provider runs, because the
|
|
32
|
+
* provider would answer it with a code whenever a consent is on record.
|
|
33
|
+
*/
|
|
34
|
+
/** The one OAuth scope this server issues. A constant, not a vocabulary. */
|
|
35
|
+
const MCP_SCOPE = "mcp";
|
|
36
|
+
/** The scopes a client may request: {@link MCP_SCOPE}, and `offline_access` for a refresh token. */
|
|
37
|
+
const MCP_SCOPES = ["mcp", "offline_access"];
|
|
38
|
+
/**
|
|
39
|
+
* The provider's tables, under this capability's prefix. Better Auth names a plugin's tables after its models;
|
|
40
|
+
* every table this kit provides is `pithy_<capability>_<table>`, so each one is renamed here, once.
|
|
41
|
+
*/
|
|
42
|
+
const MCP_MODEL_NAMES = {
|
|
43
|
+
oauthClient: "pithyMcpClients",
|
|
44
|
+
oauthResource: "pithyMcpResources",
|
|
45
|
+
oauthClientResource: "pithyMcpClientResources",
|
|
46
|
+
oauthRefreshToken: "pithyMcpRefreshTokens",
|
|
47
|
+
oauthAccessToken: "pithyMcpAccessTokens",
|
|
48
|
+
oauthConsent: "pithyMcpConsents",
|
|
49
|
+
oauthClientAssertion: "pithyMcpClientAssertions"
|
|
50
|
+
};
|
|
51
|
+
/** The plugin id of the kit's consent-every-time hook. */
|
|
52
|
+
const MCP_CONSENT_PLUGIN_ID = "pithy-mcp-consent";
|
|
53
|
+
/**
|
|
54
|
+
* The `prompt` an authorize request runs with — always including `consent` — or `null` when the client asked for
|
|
55
|
+
* `none`. `none` asks for a grant with no screen, and this server has no such grant to give.
|
|
56
|
+
*/
|
|
57
|
+
function consentPrompt(prompt) {
|
|
58
|
+
const asked = typeof prompt === "string" ? prompt.split(" ").filter((value) => value.length > 0) : [];
|
|
59
|
+
if (asked.includes("none")) return null;
|
|
60
|
+
return [.../* @__PURE__ */ new Set([...asked.filter((value) => value !== "login"), "consent"])].join(" ");
|
|
61
|
+
}
|
|
62
|
+
/** Show the consent screen on every authorization, so asking again is a decision rather than a skip. */
|
|
63
|
+
function consentEveryTime() {
|
|
64
|
+
return {
|
|
65
|
+
id: MCP_CONSENT_PLUGIN_ID,
|
|
66
|
+
hooks: { before: [{
|
|
67
|
+
matcher: (context) => context.path === "/oauth2/authorize" && context.request !== void 0 && new URL(context.request.url).pathname.endsWith("/oauth2/authorize"),
|
|
68
|
+
handler: createAuthMiddleware(async (ctx) => {
|
|
69
|
+
const query = ctx.query ?? {};
|
|
70
|
+
const prompt = consentPrompt(query.prompt);
|
|
71
|
+
if (prompt === null) throw new APIError("BAD_REQUEST", {
|
|
72
|
+
error: "consent_required",
|
|
73
|
+
error_description: "This application asks for consent every time, so prompt=none is never granted."
|
|
74
|
+
});
|
|
75
|
+
return { context: { query: {
|
|
76
|
+
...query,
|
|
77
|
+
prompt
|
|
78
|
+
} } };
|
|
79
|
+
})
|
|
80
|
+
}] }
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The provider plugin and the kit's consent hook, for one Worker's MCP endpoint.
|
|
85
|
+
*
|
|
86
|
+
* Typed as plain `BetterAuthPlugin`s, the way the kit's translator and sign-in gate are. Every reader takes them as
|
|
87
|
+
* that already: the instance's plugin list is the adopter's `BetterAuthPlugin[]` with these appended, and the
|
|
88
|
+
* migration plan reads a `BetterAuthPlugin[]`. So the widening erases nothing a caller sees, and it keeps the
|
|
89
|
+
* provider's inferred type out of the shipped declaration, which would otherwise name `better-call` internals a
|
|
90
|
+
* declaration cannot reach.
|
|
91
|
+
*/
|
|
92
|
+
function mcpAuthorizationServer(settings) {
|
|
93
|
+
return [oauthProvider({
|
|
94
|
+
loginPage: settings.consentPage,
|
|
95
|
+
consentPage: settings.consentPage,
|
|
96
|
+
scopes: [...MCP_SCOPES],
|
|
97
|
+
grantTypes: ["authorization_code", "refresh_token"],
|
|
98
|
+
allowDynamicClientRegistration: true,
|
|
99
|
+
allowUnauthenticatedClientRegistration: true,
|
|
100
|
+
clientRegistrationDefaultApplicationType: "infer",
|
|
101
|
+
extensions: [{ clientDiscovery: settings.clientDiscovery }],
|
|
102
|
+
resources: [settings.resource],
|
|
103
|
+
clientRegistrationDefaultResources: [settings.resource],
|
|
104
|
+
schema: Object.fromEntries(Object.entries(MCP_MODEL_NAMES).map(([model, modelName]) => [model, { modelName }]))
|
|
105
|
+
}), consentEveryTime()];
|
|
106
|
+
}
|
|
107
|
+
//#endregion
|
|
108
|
+
export { MCP_CONSENT_PLUGIN_ID, MCP_MODEL_NAMES, MCP_SCOPE, MCP_SCOPES, consentPrompt, mcpAuthorizationServer };
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { PurgeContext } from "@pithy-sh/core/src/capability/purge";
|
|
4
|
+
/**
|
|
5
|
+
* What erasing and exporting a person means for the provider's tables.
|
|
6
|
+
*
|
|
7
|
+
* The rows keyed to a person are the consents they gave and the tokens minted under them. A dynamically registered
|
|
8
|
+
* client is not theirs — it is the application's record of itself, written before anybody signed in — so it stays.
|
|
9
|
+
*/
|
|
10
|
+
export declare const MCP_USER_TABLES: readonly ["pithyMcpConsents", "pithyMcpAccessTokens", "pithyMcpRefreshTokens"];
|
|
11
|
+
/** Erase one person's consents and tokens. Succeeds, having found nothing, when they are already gone. */
|
|
12
|
+
export declare function eraseMcpUser(context: PurgeContext, database: string): Promise<void>;
|
|
13
|
+
/** One person's consents and tokens, every column but a credential's. */
|
|
14
|
+
export declare function exportMcpUser(context: PurgeContext, database: string): Promise<Record<string, unknown>>;
|
|
15
|
+
//# sourceMappingURL=purge.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../src/mcp/purge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAKxE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,gFAIlB,CAAC;AAEX,0GAA0G;AAC1G,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzF;AAED,yEAAyE;AACzE,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAM7G"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { authDatabase } from "../data/tables.js";
|
|
4
|
+
import { MCP_MODEL_NAMES } from "./provider.js";
|
|
5
|
+
import { bindingOf, pluginRows, prepared, untyped } from "../purge/contribution.js";
|
|
6
|
+
//#region src/mcp/purge.ts
|
|
7
|
+
/**
|
|
8
|
+
* What erasing and exporting a person means for the provider's tables.
|
|
9
|
+
*
|
|
10
|
+
* The rows keyed to a person are the consents they gave and the tokens minted under them. A dynamically registered
|
|
11
|
+
* client is not theirs — it is the application's record of itself, written before anybody signed in — so it stays.
|
|
12
|
+
*/
|
|
13
|
+
const MCP_USER_TABLES = [
|
|
14
|
+
MCP_MODEL_NAMES.oauthConsent,
|
|
15
|
+
MCP_MODEL_NAMES.oauthAccessToken,
|
|
16
|
+
MCP_MODEL_NAMES.oauthRefreshToken
|
|
17
|
+
];
|
|
18
|
+
/** Erase one person's consents and tokens. Succeeds, having found nothing, when they are already gone. */
|
|
19
|
+
async function eraseMcpUser(context, database) {
|
|
20
|
+
const d1 = bindingOf(context.env, database);
|
|
21
|
+
const db = untyped(authDatabase(d1));
|
|
22
|
+
await d1.batch(MCP_USER_TABLES.map((table) => prepared(d1, db.deleteFrom(table).where("userId", "=", context.subject.id).compile())));
|
|
23
|
+
}
|
|
24
|
+
/** One person's consents and tokens, every column but a credential's. */
|
|
25
|
+
async function exportMcpUser(context, database) {
|
|
26
|
+
const db = authDatabase(bindingOf(context.env, database));
|
|
27
|
+
const tables = await Promise.all(MCP_USER_TABLES.map(async (table) => [table, await pluginRows(db, table, context.subject.id)]));
|
|
28
|
+
return Object.fromEntries(tables);
|
|
29
|
+
}
|
|
30
|
+
//#endregion
|
|
31
|
+
export { MCP_USER_TABLES, eraseMcpUser, exportMcpUser };
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { AppTool } from "@pithy-sh/core/src/mcp/tools";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
/**
|
|
6
|
+
* The MCP protocol the endpoint speaks: streamable HTTP, stateless, JSON responses.
|
|
7
|
+
*
|
|
8
|
+
* **Four methods and one notification**, because that is the whole of a tools-only server: `initialize`, `ping`,
|
|
9
|
+
* `tools/list`, `tools/call`, and `notifications/initialized`. Each POST carries one JSON-RPC message and is
|
|
10
|
+
* answered in the response body, so there is no session to keep, no stream to hold open, and nothing an isolate
|
|
11
|
+
* has to remember between requests — the caller is re-verified on every one. A notification is answered `202`
|
|
12
|
+
* with no body.
|
|
13
|
+
*
|
|
14
|
+
* **Pure.** The handlers are handed in; this module decides what a message means and what its answer looks like,
|
|
15
|
+
* and nothing about who is asking.
|
|
16
|
+
*/
|
|
17
|
+
/** The protocol versions this server speaks, newest first. */
|
|
18
|
+
export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26"];
|
|
19
|
+
/** One JSON-RPC 2.0 message, as a client sends it. */
|
|
20
|
+
export declare const RpcMessage: z.ZodObject<{
|
|
21
|
+
jsonrpc: z.ZodLiteral<"2.0">;
|
|
22
|
+
id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
|
|
23
|
+
method: z.ZodString;
|
|
24
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
25
|
+
}, z.core.$strip>;
|
|
26
|
+
export type RpcMessage = z.infer<typeof RpcMessage>;
|
|
27
|
+
/** JSON-RPC's own error codes, the ones this server answers with. */
|
|
28
|
+
export declare const RPC_ERRORS: {
|
|
29
|
+
readonly methodNotFound: -32601;
|
|
30
|
+
readonly invalidParams: -32602;
|
|
31
|
+
readonly internal: -32603;
|
|
32
|
+
};
|
|
33
|
+
/** A tool as `tools/list` publishes it. */
|
|
34
|
+
export interface ListedTool {
|
|
35
|
+
readonly name: string;
|
|
36
|
+
readonly title: string;
|
|
37
|
+
readonly description: string;
|
|
38
|
+
readonly inputSchema: Record<string, unknown>;
|
|
39
|
+
readonly annotations: AppTool["annotations"] & {
|
|
40
|
+
readonly title: string;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/** What a tool call came back with. */
|
|
44
|
+
export interface CallOutcome {
|
|
45
|
+
/** The route's status. */
|
|
46
|
+
readonly status: number;
|
|
47
|
+
/** The route's body, parsed when it was JSON. */
|
|
48
|
+
readonly body: unknown;
|
|
49
|
+
}
|
|
50
|
+
/** What the endpoint hands the protocol: the caller's tools, and a way to call one. */
|
|
51
|
+
export interface RpcHandlers {
|
|
52
|
+
/** The server's name and version, for `initialize`. */
|
|
53
|
+
readonly server: {
|
|
54
|
+
readonly name: string;
|
|
55
|
+
readonly version: string;
|
|
56
|
+
};
|
|
57
|
+
/** The tools this caller may call. */
|
|
58
|
+
readonly tools: () => Promise<readonly AppTool[]>;
|
|
59
|
+
/** Call one, as the caller. */
|
|
60
|
+
readonly call: (tool: AppTool, args: Record<string, unknown>) => Promise<CallOutcome>;
|
|
61
|
+
/** Told of a `tools/call` naming a tool the caller was not offered, before it is answered as unknown. */
|
|
62
|
+
readonly refused: (name: unknown) => Promise<void>;
|
|
63
|
+
}
|
|
64
|
+
/** A JSON-RPC answer, or `null` for a notification. */
|
|
65
|
+
export type RpcAnswer = {
|
|
66
|
+
jsonrpc: "2.0";
|
|
67
|
+
id: string | number;
|
|
68
|
+
result?: unknown;
|
|
69
|
+
error?: unknown;
|
|
70
|
+
} | null;
|
|
71
|
+
/** A tool as `tools/list` publishes it. */
|
|
72
|
+
export declare function listedTool(tool: AppTool): ListedTool;
|
|
73
|
+
/** The version to answer `initialize` with: the client's, when this server speaks it, or the newest. */
|
|
74
|
+
export declare function negotiatedVersion(requested: unknown): string;
|
|
75
|
+
/** A call's outcome as an MCP tool result: the body as text, and as structured content when it is an object. */
|
|
76
|
+
export declare function toolResult(outcome: CallOutcome): Record<string, unknown>;
|
|
77
|
+
/** Answer one message. */
|
|
78
|
+
export declare function answer(message: RpcMessage, handlers: RpcHandlers): Promise<RpcAnswer>;
|
|
79
|
+
//# sourceMappingURL=rpc.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../src/mcp/rpc.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,YAAI,YAAY,EAAE,YAAY,CAAU,CAAC;AAE3E,sDAAsD;AACtD,eAAO,MAAM,UAAU;;;;;iBAUiC,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,qEAAqE;AACrE,eAAO,MAAM,UAAU;aAAK,cAAc,EAAE,CAAC,KAAK;aAAE,aAAa,EAAE,CAAC,KAAK;aAAE,QAAQ,EAAE,CAAC,KAAK;CAAW,CAAC;AAEvG,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IAClD,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACtF,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC;AAE1G,2CAA2C;AAC3C,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAQpD;AAED,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI5D;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOxE;AAMD,0BAA0B;AAC1B,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CA8B3F"}
|
package/dist/mcp/rpc.js
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
//#region src/mcp/rpc.ts
|
|
5
|
+
/**
|
|
6
|
+
* The MCP protocol the endpoint speaks: streamable HTTP, stateless, JSON responses.
|
|
7
|
+
*
|
|
8
|
+
* **Four methods and one notification**, because that is the whole of a tools-only server: `initialize`, `ping`,
|
|
9
|
+
* `tools/list`, `tools/call`, and `notifications/initialized`. Each POST carries one JSON-RPC message and is
|
|
10
|
+
* answered in the response body, so there is no session to keep, no stream to hold open, and nothing an isolate
|
|
11
|
+
* has to remember between requests — the caller is re-verified on every one. A notification is answered `202`
|
|
12
|
+
* with no body.
|
|
13
|
+
*
|
|
14
|
+
* **Pure.** The handlers are handed in; this module decides what a message means and what its answer looks like,
|
|
15
|
+
* and nothing about who is asking.
|
|
16
|
+
*/
|
|
17
|
+
/** The protocol versions this server speaks, newest first. */
|
|
18
|
+
const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26"];
|
|
19
|
+
/** One JSON-RPC 2.0 message, as a client sends it. */
|
|
20
|
+
const RpcMessage = z.object({
|
|
21
|
+
jsonrpc: z.literal("2.0").describe("Always `2.0`."),
|
|
22
|
+
id: z.union([z.string(), z.number()]).optional().describe("The request's id. Absent on a notification, which gets no answer."),
|
|
23
|
+
method: z.string().min(1).describe("The method called, e.g. `tools/list`."),
|
|
24
|
+
params: z.record(z.string(), z.unknown()).optional().describe("The method's parameters.")
|
|
25
|
+
}).describe("One JSON-RPC 2.0 request or notification.");
|
|
26
|
+
/** JSON-RPC's own error codes, the ones this server answers with. */
|
|
27
|
+
const RPC_ERRORS = {
|
|
28
|
+
methodNotFound: -32601,
|
|
29
|
+
invalidParams: -32602,
|
|
30
|
+
internal: -32603
|
|
31
|
+
};
|
|
32
|
+
/** A tool as `tools/list` publishes it. */
|
|
33
|
+
function listedTool(tool) {
|
|
34
|
+
return {
|
|
35
|
+
name: tool.name,
|
|
36
|
+
title: tool.summary,
|
|
37
|
+
description: tool.description,
|
|
38
|
+
inputSchema: tool.inputSchema,
|
|
39
|
+
annotations: {
|
|
40
|
+
title: tool.summary,
|
|
41
|
+
...tool.annotations
|
|
42
|
+
}
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
/** The version to answer `initialize` with: the client's, when this server speaks it, or the newest. */
|
|
46
|
+
function negotiatedVersion(requested) {
|
|
47
|
+
return typeof requested === "string" && MCP_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSIONS[0];
|
|
48
|
+
}
|
|
49
|
+
/** A call's outcome as an MCP tool result: the body as text, and as structured content when it is an object. */
|
|
50
|
+
function toolResult(outcome) {
|
|
51
|
+
const text = typeof outcome.body === "string" ? outcome.body : JSON.stringify(outcome.body ?? null);
|
|
52
|
+
const structured = outcome.body !== null && typeof outcome.body === "object" && !Array.isArray(outcome.body) ? { structuredContent: outcome.body } : {};
|
|
53
|
+
return {
|
|
54
|
+
content: [{
|
|
55
|
+
type: "text",
|
|
56
|
+
text
|
|
57
|
+
}],
|
|
58
|
+
...structured,
|
|
59
|
+
isError: outcome.status >= 400
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
function record(value) {
|
|
63
|
+
return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
|
|
64
|
+
}
|
|
65
|
+
/** Answer one message. */
|
|
66
|
+
async function answer(message, handlers) {
|
|
67
|
+
if (message.id === void 0) return null;
|
|
68
|
+
const id = message.id;
|
|
69
|
+
const ok = (result) => ({
|
|
70
|
+
jsonrpc: "2.0",
|
|
71
|
+
id,
|
|
72
|
+
result
|
|
73
|
+
});
|
|
74
|
+
const fail = (code, text) => ({
|
|
75
|
+
jsonrpc: "2.0",
|
|
76
|
+
id,
|
|
77
|
+
error: {
|
|
78
|
+
code,
|
|
79
|
+
message: text
|
|
80
|
+
}
|
|
81
|
+
});
|
|
82
|
+
switch (message.method) {
|
|
83
|
+
case "initialize": return ok({
|
|
84
|
+
protocolVersion: negotiatedVersion(message.params?.protocolVersion),
|
|
85
|
+
capabilities: { tools: { listChanged: false } },
|
|
86
|
+
serverInfo: handlers.server
|
|
87
|
+
});
|
|
88
|
+
case "ping": return ok({});
|
|
89
|
+
case "tools/list": return ok({ tools: (await handlers.tools()).map(listedTool) });
|
|
90
|
+
case "tools/call": {
|
|
91
|
+
const name = message.params?.name;
|
|
92
|
+
const tool = (await handlers.tools()).find((entry) => entry.name === name);
|
|
93
|
+
if (tool === void 0) {
|
|
94
|
+
await handlers.refused(name);
|
|
95
|
+
return fail(RPC_ERRORS.invalidParams, `Unknown tool: ${String(name)}.`);
|
|
96
|
+
}
|
|
97
|
+
return ok(toolResult(await handlers.call(tool, record(message.params?.arguments))));
|
|
98
|
+
}
|
|
99
|
+
default: return fail(RPC_ERRORS.methodNotFound, `Method not found: ${message.method}.`);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
//#endregion
|
|
103
|
+
export { MCP_PROTOCOL_VERSIONS, RPC_ERRORS, RpcMessage, answer, listedTool, negotiatedVersion, toolResult };
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { AuditEventInput, AuditOutcome } from "@pithy-sh/core/src/audit/auditEvent";
|
|
4
|
+
import { type AuditEmit } from "@pithy-sh/core/src/audit/recorder";
|
|
5
|
+
import type { ArgumentClass } from "./argumentClass";
|
|
6
|
+
/**
|
|
7
|
+
* The audit row an in-Worker MCP tool call writes (`docs/AGENT-ACCESS.md` §9).
|
|
8
|
+
*
|
|
9
|
+
* **Who acted.** The call ran under the user's authority, so the row is `actorType: "user"` with their id — and
|
|
10
|
+
* `actorKind: "agent"`, the field control-plane rows already carry, so one filter finds every agent row on both
|
|
11
|
+
* paths. The client is in `metadata`: its id, and its name as it reported itself, which nothing has verified.
|
|
12
|
+
*
|
|
13
|
+
* **What it cost.** The route's status, the wall time from receiving the call to answering it, and the size of the
|
|
14
|
+
* route's response. CPU time is not readable per request in a Worker, so the row does not claim it.
|
|
15
|
+
*/
|
|
16
|
+
/** The action codes the MCP endpoint emits, under the `mcp` domain. */
|
|
17
|
+
export declare const McpAuditActions: {
|
|
18
|
+
/**
|
|
19
|
+
* One `tools/call`. Outcome `success`, `failure` when the route answered an error, or `denied` when the tool was
|
|
20
|
+
* never offered to the caller or the route refused them.
|
|
21
|
+
*/
|
|
22
|
+
readonly toolCall: "mcp/tool_call";
|
|
23
|
+
};
|
|
24
|
+
/** The longest tool name a row records. A name the caller made up is theirs to make as long as they like. */
|
|
25
|
+
export declare const MAX_TOOL_NAME = 128;
|
|
26
|
+
/** The longest client name a row records. The client chose its own name at registration. */
|
|
27
|
+
export declare const MAX_CLIENT_NAME = 128;
|
|
28
|
+
/** The tool a `tools/call` named, as a row records it: a string, bounded, or null. */
|
|
29
|
+
export declare function requestedToolName(name: unknown): string | null;
|
|
30
|
+
/** The outcome a route's status records: a refusal is `denied`, any other error `failure`. */
|
|
31
|
+
export declare function toolCallOutcome(status: number): AuditOutcome;
|
|
32
|
+
/** Who made a call: the user, the session the token was minted under, and the client acting for them. */
|
|
33
|
+
export interface ToolCallActor {
|
|
34
|
+
readonly userId: string;
|
|
35
|
+
readonly sessionId: string;
|
|
36
|
+
readonly clientId: string;
|
|
37
|
+
/** The client's name as it registered itself. Self-asserted; never verified. */
|
|
38
|
+
readonly clientReportedName: string | null;
|
|
39
|
+
/** The acting organization, or null where none is in force. */
|
|
40
|
+
readonly tenant: string | null;
|
|
41
|
+
}
|
|
42
|
+
/** What ties the row to the rest of the request: the route's own rows carry the same `requestId`. */
|
|
43
|
+
export interface ToolCallCorrelation {
|
|
44
|
+
readonly requestId: string;
|
|
45
|
+
readonly ip: string | null;
|
|
46
|
+
readonly userAgent: string | null;
|
|
47
|
+
}
|
|
48
|
+
/** What came of a call: the route answered it, or it was never dispatched. */
|
|
49
|
+
export type ToolCallResult = {
|
|
50
|
+
readonly kind: "answered";
|
|
51
|
+
readonly status: number;
|
|
52
|
+
readonly responseBytes: number;
|
|
53
|
+
readonly arguments: ArgumentClass;
|
|
54
|
+
}
|
|
55
|
+
/** `withheld`: a tool this app has that the caller's role was not offered. `unknown`: no such tool. */
|
|
56
|
+
| {
|
|
57
|
+
readonly kind: "refused";
|
|
58
|
+
readonly reason: "withheld" | "unknown";
|
|
59
|
+
};
|
|
60
|
+
/** Everything one row is built from. */
|
|
61
|
+
export interface ToolCallRecord {
|
|
62
|
+
readonly actor: ToolCallActor;
|
|
63
|
+
readonly correlation: ToolCallCorrelation;
|
|
64
|
+
/** The tool's name, or null when the call named none. */
|
|
65
|
+
readonly tool: string | null;
|
|
66
|
+
readonly durationMs: number;
|
|
67
|
+
readonly result: ToolCallResult;
|
|
68
|
+
}
|
|
69
|
+
/** The audit event for one tool call. */
|
|
70
|
+
export declare function toolCallEvent(record: ToolCallRecord): AuditEventInput;
|
|
71
|
+
/**
|
|
72
|
+
* Write one row, and never fail the call it records: the row is evidence of what happened, never part of making it
|
|
73
|
+
* happen. With no audit capability composed the event is not even built, since building it reads the client's row.
|
|
74
|
+
*/
|
|
75
|
+
export declare function recordToolCall(emit: AuditEmit, build: () => Promise<AuditEventInput>): Promise<void>;
|
|
76
|
+
//# sourceMappingURL=toolAudit.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"toolAudit.d.ts","sourceRoot":"","sources":["../../src/mcp/toolAudit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACzF,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,mCAAmC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;GASG;AAEH,uEAAuE;AACvE,eAAO,MAAM,eAAe;IAC1B;;;OAGG;aACH,QAAQ,EAAE,eAAe;CACjB,CAAC;AAEX,6GAA6G;AAC7G,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,4FAA4F;AAC5F,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE9D;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAG5D;AAED,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,qGAAqG;AACrG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;CACnC;AACH,uGAAuG;GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,yCAAyC;AACzC,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAkCrE;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1G"}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { noopEmit } from "@pithy-sh/core/src/audit/recorder";
|
|
4
|
+
//#region src/mcp/toolAudit.ts
|
|
5
|
+
/**
|
|
6
|
+
* The audit row an in-Worker MCP tool call writes (`docs/AGENT-ACCESS.md` §9).
|
|
7
|
+
*
|
|
8
|
+
* **Who acted.** The call ran under the user's authority, so the row is `actorType: "user"` with their id — and
|
|
9
|
+
* `actorKind: "agent"`, the field control-plane rows already carry, so one filter finds every agent row on both
|
|
10
|
+
* paths. The client is in `metadata`: its id, and its name as it reported itself, which nothing has verified.
|
|
11
|
+
*
|
|
12
|
+
* **What it cost.** The route's status, the wall time from receiving the call to answering it, and the size of the
|
|
13
|
+
* route's response. CPU time is not readable per request in a Worker, so the row does not claim it.
|
|
14
|
+
*/
|
|
15
|
+
/** The action codes the MCP endpoint emits, under the `mcp` domain. */
|
|
16
|
+
const McpAuditActions = {
|
|
17
|
+
/**
|
|
18
|
+
* One `tools/call`. Outcome `success`, `failure` when the route answered an error, or `denied` when the tool was
|
|
19
|
+
* never offered to the caller or the route refused them.
|
|
20
|
+
*/
|
|
21
|
+
toolCall: "mcp/tool_call" };
|
|
22
|
+
/** The longest tool name a row records. A name the caller made up is theirs to make as long as they like. */
|
|
23
|
+
const MAX_TOOL_NAME = 128;
|
|
24
|
+
/** The longest client name a row records. The client chose its own name at registration. */
|
|
25
|
+
const MAX_CLIENT_NAME = 128;
|
|
26
|
+
/** The tool a `tools/call` named, as a row records it: a string, bounded, or null. */
|
|
27
|
+
function requestedToolName(name) {
|
|
28
|
+
return typeof name === "string" ? name.slice(0, 128) : null;
|
|
29
|
+
}
|
|
30
|
+
/** The outcome a route's status records: a refusal is `denied`, any other error `failure`. */
|
|
31
|
+
function toolCallOutcome(status) {
|
|
32
|
+
if (status === 401 || status === 403) return "denied";
|
|
33
|
+
return status >= 400 ? "failure" : "success";
|
|
34
|
+
}
|
|
35
|
+
/** The audit event for one tool call. */
|
|
36
|
+
function toolCallEvent(record) {
|
|
37
|
+
const { actor, correlation, tool, durationMs, result } = record;
|
|
38
|
+
const outcome = result.kind === "answered" ? toolCallOutcome(result.status) : "denied";
|
|
39
|
+
const client = {
|
|
40
|
+
clientId: actor.clientId,
|
|
41
|
+
clientReportedName: actor.clientReportedName?.slice(0, 128) ?? null
|
|
42
|
+
};
|
|
43
|
+
const metadata = result.kind === "answered" ? {
|
|
44
|
+
tool,
|
|
45
|
+
...client,
|
|
46
|
+
status: result.status,
|
|
47
|
+
durationMs,
|
|
48
|
+
responseBytes: result.responseBytes,
|
|
49
|
+
arguments: result.arguments
|
|
50
|
+
} : {
|
|
51
|
+
tool,
|
|
52
|
+
...client,
|
|
53
|
+
status: null,
|
|
54
|
+
durationMs,
|
|
55
|
+
responseBytes: null,
|
|
56
|
+
refused: result.reason
|
|
57
|
+
};
|
|
58
|
+
return {
|
|
59
|
+
action: McpAuditActions.toolCall,
|
|
60
|
+
outcome,
|
|
61
|
+
severity: outcome === "denied" ? "warning" : "info",
|
|
62
|
+
actorType: "user",
|
|
63
|
+
actorId: actor.userId,
|
|
64
|
+
actorKind: "agent",
|
|
65
|
+
sessionId: actor.sessionId,
|
|
66
|
+
tenant: actor.tenant,
|
|
67
|
+
resourceType: "mcp_tool",
|
|
68
|
+
resourceId: tool,
|
|
69
|
+
requestId: correlation.requestId,
|
|
70
|
+
ip: correlation.ip,
|
|
71
|
+
userAgent: correlation.userAgent,
|
|
72
|
+
metadata
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Write one row, and never fail the call it records: the row is evidence of what happened, never part of making it
|
|
77
|
+
* happen. With no audit capability composed the event is not even built, since building it reads the client's row.
|
|
78
|
+
*/
|
|
79
|
+
async function recordToolCall(emit, build) {
|
|
80
|
+
if (emit === noopEmit) return;
|
|
81
|
+
try {
|
|
82
|
+
await emit(await build());
|
|
83
|
+
} catch {}
|
|
84
|
+
}
|
|
85
|
+
//#endregion
|
|
86
|
+
export { MAX_CLIENT_NAME, MAX_TOOL_NAME, McpAuditActions, recordToolCall, requestedToolName, toolCallEvent, toolCallOutcome };
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { Migration } from "kysely/migration";
|
|
4
|
+
/**
|
|
5
|
+
* The verification ledger (#829): `pithy_auth_verification_outcomes`, one row per sign-in link or code auth
|
|
6
|
+
* issues, stamped when it is used. See `../data/verificationOutcome.ts` for why it exists and what it never holds.
|
|
7
|
+
*
|
|
8
|
+
* **Every date is `integer`**, ms-epoch: nothing but the kit writes this table. **No backfill**: the links and
|
|
9
|
+
* codes issued before this ran left nothing to read back — a used one was deleted on use — so the ledger starts
|
|
10
|
+
* empty, and a window reaching back before the upgrade counts only what was issued after it.
|
|
11
|
+
*
|
|
12
|
+
* **A `0006`, appended.** `@pithy-sh/auth` has shipped, so its chain is history.
|
|
13
|
+
*/
|
|
14
|
+
export declare const auth_0006_verification_outcomes: Migration;
|
|
15
|
+
//# sourceMappingURL=0006_verification_outcomes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"0006_verification_outcomes.d.ts","sourceRoot":"","sources":["../../src/migrations/0006_verification_outcomes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASlD;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,SA2B7C,CAAC"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
//#region src/migrations/0006_verification_outcomes.ts
|
|
4
|
+
/** The window read's index: rows issued in a range, newest first, the id ordering a millisecond's ties. */
|
|
5
|
+
const ISSUED_INDEX = "pithyAuthVerificationOutcomesIssuedAtIdx";
|
|
6
|
+
/** How a use finds the row it stamps, and how a wrong code's re-issue moves it. */
|
|
7
|
+
const VERIFICATION_INDEX = "pithyAuthVerificationOutcomesVerificationIdIdx";
|
|
8
|
+
/** How a purge finds an account's rows. */
|
|
9
|
+
const USER_INDEX = "pithyAuthVerificationOutcomesUserIdIdx";
|
|
10
|
+
/**
|
|
11
|
+
* The verification ledger (#829): `pithy_auth_verification_outcomes`, one row per sign-in link or code auth
|
|
12
|
+
* issues, stamped when it is used. See `../data/verificationOutcome.ts` for why it exists and what it never holds.
|
|
13
|
+
*
|
|
14
|
+
* **Every date is `integer`**, ms-epoch: nothing but the kit writes this table. **No backfill**: the links and
|
|
15
|
+
* codes issued before this ran left nothing to read back — a used one was deleted on use — so the ledger starts
|
|
16
|
+
* empty, and a window reaching back before the upgrade counts only what was issued after it.
|
|
17
|
+
*
|
|
18
|
+
* **A `0006`, appended.** `@pithy-sh/auth` has shipped, so its chain is history.
|
|
19
|
+
*/
|
|
20
|
+
const auth_0006_verification_outcomes = {
|
|
21
|
+
async up(db) {
|
|
22
|
+
await db.schema.createTable("pithyAuthVerificationOutcomes").addColumn("id", "integer", (c) => c.primaryKey().autoIncrement()).addColumn("verificationId", "text", (c) => c.notNull()).addColumn("type", "text", (c) => c.notNull()).addColumn("userId", "text").addColumn("emailJobId", "text").addColumn("issuedAt", "integer", (c) => c.notNull()).addColumn("expiresAt", "integer", (c) => c.notNull()).addColumn("usedAt", "integer").execute();
|
|
23
|
+
await db.schema.createIndex(ISSUED_INDEX).on("pithyAuthVerificationOutcomes").columns(["issuedAt", "id"]).execute();
|
|
24
|
+
await db.schema.createIndex(VERIFICATION_INDEX).on("pithyAuthVerificationOutcomes").column("verificationId").execute();
|
|
25
|
+
await db.schema.createIndex(USER_INDEX).on("pithyAuthVerificationOutcomes").column("userId").execute();
|
|
26
|
+
},
|
|
27
|
+
async down(db) {
|
|
28
|
+
await db.schema.dropIndex(USER_INDEX).execute();
|
|
29
|
+
await db.schema.dropIndex(VERIFICATION_INDEX).execute();
|
|
30
|
+
await db.schema.dropIndex(ISSUED_INDEX).execute();
|
|
31
|
+
await db.schema.dropTable("pithyAuthVerificationOutcomes").execute();
|
|
32
|
+
}
|
|
33
|
+
};
|
|
34
|
+
//#endregion
|
|
35
|
+
export { auth_0006_verification_outcomes };
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { Migration } from "kysely/migration";
|
|
4
|
+
/**
|
|
5
|
+
* The erasure record (#823): what a deletion asked for, kept where the purge cannot erase it.
|
|
6
|
+
*
|
|
7
|
+
* **`mode` and `purge_after` on `pithy_auth_user_lifecycle`.** The attestation says whether a deletion was soft or
|
|
8
|
+
* hard and when its purge came due. Both sat only on `pithy_auth_users`, as `purgeAfter`, or nowhere, and the purge
|
|
9
|
+
* erases that row. So a `deleted` row now carries them: `soft` or `hard`, and the instant, ms-epoch. Null on every
|
|
10
|
+
* other row, and on a deletion recorded before this ran — the attestation says so rather than guessing.
|
|
11
|
+
*
|
|
12
|
+
* **Two indexes for the period read**, which asks which purges came due, ran a step, failed or finished in a window.
|
|
13
|
+
*
|
|
14
|
+
* **A `0007`, appended.** `@pithy-sh/auth` has shipped, so its chain is history. No backfill.
|
|
15
|
+
*/
|
|
16
|
+
export declare const auth_0007_erasure_record: Migration;
|
|
17
|
+
//# sourceMappingURL=0007_erasure_record.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"0007_erasure_record.d.ts","sourceRoot":"","sources":["../../src/migrations/0007_erasure_record.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQlD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAkBtC,CAAC"}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { sql } from "kysely";
|
|
4
|
+
//#region src/migrations/0007_erasure_record.ts
|
|
5
|
+
/** The period read's index: every erasure row written in a window. */
|
|
6
|
+
const CREATED_INDEX = "pithyAuthUserLifecycleCreatedAtIdx";
|
|
7
|
+
/** The period read's other index: every deletion whose purge came due in a window. */
|
|
8
|
+
const PURGE_AFTER_INDEX = "pithyAuthUserLifecyclePurgeAfterIdx";
|
|
9
|
+
/**
|
|
10
|
+
* The erasure record (#823): what a deletion asked for, kept where the purge cannot erase it.
|
|
11
|
+
*
|
|
12
|
+
* **`mode` and `purge_after` on `pithy_auth_user_lifecycle`.** The attestation says whether a deletion was soft or
|
|
13
|
+
* hard and when its purge came due. Both sat only on `pithy_auth_users`, as `purgeAfter`, or nowhere, and the purge
|
|
14
|
+
* erases that row. So a `deleted` row now carries them: `soft` or `hard`, and the instant, ms-epoch. Null on every
|
|
15
|
+
* other row, and on a deletion recorded before this ran — the attestation says so rather than guessing.
|
|
16
|
+
*
|
|
17
|
+
* **Two indexes for the period read**, which asks which purges came due, ran a step, failed or finished in a window.
|
|
18
|
+
*
|
|
19
|
+
* **A `0007`, appended.** `@pithy-sh/auth` has shipped, so its chain is history. No backfill.
|
|
20
|
+
*/
|
|
21
|
+
const auth_0007_erasure_record = {
|
|
22
|
+
async up(db) {
|
|
23
|
+
await db.schema.alterTable("pithyAuthUserLifecycle").addColumn("mode", "text").execute();
|
|
24
|
+
await db.schema.alterTable("pithyAuthUserLifecycle").addColumn("purgeAfter", "integer").execute();
|
|
25
|
+
await db.schema.createIndex(CREATED_INDEX).on("pithyAuthUserLifecycle").column("createdAt").execute();
|
|
26
|
+
await db.schema.createIndex(PURGE_AFTER_INDEX).on("pithyAuthUserLifecycle").column("purgeAfter").where(sql`purge_after is not null`).execute();
|
|
27
|
+
},
|
|
28
|
+
async down(db) {
|
|
29
|
+
await db.schema.dropIndex(PURGE_AFTER_INDEX).execute();
|
|
30
|
+
await db.schema.dropIndex(CREATED_INDEX).execute();
|
|
31
|
+
await db.schema.alterTable("pithyAuthUserLifecycle").dropColumn("purgeAfter").execute();
|
|
32
|
+
await db.schema.alterTable("pithyAuthUserLifecycle").dropColumn("mode").execute();
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
//#endregion
|
|
36
|
+
export { auth_0007_erasure_record };
|