@pithy-sh/auth 0.11.0 → 0.12.1
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,154 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import type { AuthContext } from "@pithy-sh/core/src/http/authContext";
|
|
6
|
+
import type { AppTool } from "@pithy-sh/core/src/mcp/tools";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* A tool call, made as the user it acts for (`docs/AGENT-ACCESS.md` §4.1).
|
|
10
|
+
*
|
|
11
|
+
* **A call is a request to the route, through the whole app, and nothing else.** The MCP endpoint builds the
|
|
12
|
+
* request the route would have received from the user's own client — its method, its path with the parameters
|
|
13
|
+
* filled in, its query and its JSON body — and hands it to the composed app. Every middleware runs, every guard
|
|
14
|
+
* runs, the route's `describeRoute({ power })` gate runs, and the route's own in-handler checks run. So the tool
|
|
15
|
+
* does exactly what the route allows this user, and **nothing consults the token for permission**: the endpoint
|
|
16
|
+
* verified who the caller is, and the role decides what they may do. There is no second gate to keep in step.
|
|
17
|
+
*
|
|
18
|
+
* **Who it is, carried in process.** The request carries no credential. The verified identity rides beside it in
|
|
19
|
+
* a `WeakMap` keyed by the request object itself, which nothing outside this isolate can reach or forge — a header
|
|
20
|
+
* would be a credential a client could send. The session middleware reads it ({@link dispatchedAuth}) and publishes
|
|
21
|
+
* it as `c.var.auth`, exactly as it would a session it resolved.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
const dispatched = new WeakMap<Request, AuthContext>();
|
|
25
|
+
|
|
26
|
+
/** The identity a dispatched request runs as, or `undefined` for every request that arrived over the network. */
|
|
27
|
+
export function dispatchedAuth(request: Request): AuthContext | undefined {
|
|
28
|
+
return dispatched.get(request);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** A call's arguments, as the tool's input schema shaped them: `{ path, query, body }`. */
|
|
32
|
+
export interface ToolArguments {
|
|
33
|
+
readonly path?: Record<string, unknown>;
|
|
34
|
+
readonly query?: Record<string, unknown>;
|
|
35
|
+
readonly body?: unknown;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function record(value: unknown): Record<string, unknown> | undefined {
|
|
39
|
+
return value !== null && typeof value === "object" && !Array.isArray(value)
|
|
40
|
+
? (value as Record<string, unknown>)
|
|
41
|
+
: undefined;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Split a call's arguments back out along the three keys the input schema joined them under. */
|
|
45
|
+
export function toolArguments(args: Record<string, unknown>): ToolArguments {
|
|
46
|
+
const path = record(args.path);
|
|
47
|
+
const query = record(args.query);
|
|
48
|
+
return {
|
|
49
|
+
...(path === undefined ? {} : { path }),
|
|
50
|
+
...(query === undefined ? {} : { query }),
|
|
51
|
+
...(args.body === undefined ? {} : { body: args.body }),
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function missing(name: string, tool: AppTool): never {
|
|
56
|
+
throw new ValidationError({
|
|
57
|
+
message: `The tool ${tool.name} needs path.${name}.`,
|
|
58
|
+
detail: `tool ${tool.name} (${tool.method} ${tool.path}) was called without path parameter ${name}`,
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function elsewhere(tool: AppTool, detail: string): never {
|
|
63
|
+
throw new ValidationError({
|
|
64
|
+
message: `The tool ${tool.name} cannot be called with that path.`,
|
|
65
|
+
detail: `tool ${tool.name} (${tool.method} ${tool.path}): ${detail}`,
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** `.` and `..` survive `encodeURIComponent`, and the URL parser collapses them into a different route. */
|
|
70
|
+
function isDotSegment(segment: string): boolean {
|
|
71
|
+
return segment === "." || segment === "..";
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** One path segment, encoded so it stays one segment, and refused when it is empty or a dot segment. */
|
|
75
|
+
function segment(name: string, value: string, tool: AppTool): string {
|
|
76
|
+
if (value.length === 0) return missing(name, tool);
|
|
77
|
+
if (isDotSegment(value)) return elsewhere(tool, `path.${name} is the dot segment "${value}"`);
|
|
78
|
+
return encodeURIComponent(value);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The URL path and query a call reaches: Hono's `:name` and `:name{pattern}` filled from `path`, each segment
|
|
83
|
+
* encoded so a value cannot add a segment of its own, and `query` as a search string. A value that is a dot
|
|
84
|
+
* segment is refused, since it would climb out of the tool's route into one that never declared itself a tool.
|
|
85
|
+
*/
|
|
86
|
+
export function toolUrl(tool: AppTool, args: ToolArguments): string {
|
|
87
|
+
const path = tool.path
|
|
88
|
+
.replace(/:([A-Za-z0-9_]+)(\{[^}]*\})?\??/g, (_match, name: string) => {
|
|
89
|
+
const value = args.path?.[name];
|
|
90
|
+
if (value === undefined || value === null) return missing(name, tool);
|
|
91
|
+
return segment(name, String(value), tool);
|
|
92
|
+
})
|
|
93
|
+
.replace(/\*$/, () => {
|
|
94
|
+
const value = args.path?.path;
|
|
95
|
+
if (value === undefined) return missing("path", tool);
|
|
96
|
+
const segments = String(value).split("/");
|
|
97
|
+
if (segments.some(isDotSegment)) return elsewhere(tool, "path.path holds a dot segment");
|
|
98
|
+
return segments.map(encodeURIComponent).join("/");
|
|
99
|
+
});
|
|
100
|
+
const search = new URLSearchParams();
|
|
101
|
+
for (const [key, value] of Object.entries(args.query ?? {})) {
|
|
102
|
+
if (value === undefined || value === null) continue;
|
|
103
|
+
for (const item of Array.isArray(value) ? value : [value]) search.append(key, String(item));
|
|
104
|
+
}
|
|
105
|
+
const query = search.toString();
|
|
106
|
+
return query.length === 0 ? path : `${path}?${query}`;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* The request a call makes to its route, registered to run as `auth`. Refused when the URL parser would read the
|
|
111
|
+
* built path as any other path: whatever the reason, the request would then reach a route the tool is not.
|
|
112
|
+
*
|
|
113
|
+
* `correlation` is copied onto it — the request id as `cf-ray`, where every route reads it, and the caller's address
|
|
114
|
+
* and user agent — so the rows the route writes join the tool call's own. None of it is a credential.
|
|
115
|
+
*/
|
|
116
|
+
export function dispatchRequest(
|
|
117
|
+
origin: string,
|
|
118
|
+
tool: AppTool,
|
|
119
|
+
args: ToolArguments,
|
|
120
|
+
auth: AuthContext,
|
|
121
|
+
correlation: Readonly<Record<string, string>> = {},
|
|
122
|
+
): Request {
|
|
123
|
+
const hasBody = args.body !== undefined && tool.method !== "GET" && tool.method !== "HEAD";
|
|
124
|
+
const built = toolUrl(tool, args);
|
|
125
|
+
const url = new URL(built, origin);
|
|
126
|
+
const builtPath = built.split("?")[0] ?? built;
|
|
127
|
+
if (url.pathname !== builtPath) elsewhere(tool, `${builtPath} resolves to ${url.pathname}`);
|
|
128
|
+
const request = new Request(url, {
|
|
129
|
+
method: tool.method,
|
|
130
|
+
headers: {
|
|
131
|
+
...correlation,
|
|
132
|
+
accept: "application/json",
|
|
133
|
+
...(hasBody ? { "content-type": "application/json" } : {}),
|
|
134
|
+
},
|
|
135
|
+
...(hasBody ? { body: JSON.stringify(args.body) } : {}),
|
|
136
|
+
});
|
|
137
|
+
dispatched.set(request, auth);
|
|
138
|
+
return request;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** A route's answer, as a tool call reports it: the status, the body parsed when it is JSON, and its size in bytes. */
|
|
142
|
+
export async function dispatchedOutcome(response: Response): Promise<{ status: number; body: unknown; bytes: number }> {
|
|
143
|
+
const raw = new Uint8Array(await response.arrayBuffer());
|
|
144
|
+
const text = new TextDecoder().decode(raw);
|
|
145
|
+
const bytes = raw.byteLength;
|
|
146
|
+
if ((response.headers.get("content-type") ?? "").includes("json")) {
|
|
147
|
+
try {
|
|
148
|
+
return { status: response.status, body: JSON.parse(text) as unknown, bytes };
|
|
149
|
+
} catch {
|
|
150
|
+
return { status: response.status, body: text, bytes };
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
return { status: response.status, body: text, bytes };
|
|
154
|
+
}
|
package/src/mcp/floor.ts
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Who the MCP endpoint admits at all (`docs/AGENT-ACCESS.md` §4).
|
|
8
|
+
*
|
|
9
|
+
* **The default is closed.** Correct route gates are not the whole question: an endpoint that lets any signed-in
|
|
10
|
+
* user drive an agent against the application is remote automation of a surface built for a person at a keyboard,
|
|
11
|
+
* which changes rate, cost and abuse patterns even when every gate holds. So the capability is off unless composed,
|
|
12
|
+
* and composing it means choosing one of three floors — there is no default to fall into:
|
|
13
|
+
*
|
|
14
|
+
* - `{ power }` — a caller whose role in the acting organization holds this power.
|
|
15
|
+
* - `{ entitlement }` — a caller holding this entitlement, a tier floor.
|
|
16
|
+
* - `"signed-in"` — every signed-in user. A decision, stated in config, and `pithy doctor` says it out loud.
|
|
17
|
+
*
|
|
18
|
+
* The floor is the endpoint's, not a tool's. Above it, every tool is still gated by its own route.
|
|
19
|
+
*/
|
|
20
|
+
export const McpFloor = z
|
|
21
|
+
.union([
|
|
22
|
+
z.literal("signed-in").describe("Every signed-in user may connect an agent. `pithy doctor` reports it as open."),
|
|
23
|
+
z
|
|
24
|
+
.object({ power: z.string().min(1).describe("The power a caller's role must hold, e.g. `agents:use`.") })
|
|
25
|
+
.strict()
|
|
26
|
+
.describe("Only a caller whose role holds this power."),
|
|
27
|
+
z
|
|
28
|
+
.object({ entitlement: z.string().min(1).describe("The entitlement a caller must hold, e.g. `pro`.") })
|
|
29
|
+
.strict()
|
|
30
|
+
.describe("Only a caller holding this entitlement."),
|
|
31
|
+
])
|
|
32
|
+
.describe(
|
|
33
|
+
"Who the MCP endpoint admits at all. Required: a power, an entitlement, or `signed-in` for every signed-in user. Every tool is still gated by its own route above it.",
|
|
34
|
+
);
|
|
35
|
+
export type McpFloor = z.infer<typeof McpFloor>;
|
|
36
|
+
|
|
37
|
+
/** What a caller holds, for {@link floorAdmits}. */
|
|
38
|
+
export interface FloorCaller {
|
|
39
|
+
/** Whether the caller's role holds a power, or `null` when no organization is in force. */
|
|
40
|
+
readonly roleAllows: ((power: string) => boolean) | null;
|
|
41
|
+
/** The entitlement keys the caller holds and that grant access now. */
|
|
42
|
+
readonly entitlements: () => Promise<ReadonlySet<string>>;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Whether the floor admits this signed-in caller. */
|
|
46
|
+
export async function floorAdmits(floor: McpFloor, caller: FloorCaller): Promise<boolean> {
|
|
47
|
+
if (floor === "signed-in") return true;
|
|
48
|
+
if ("power" in floor) return caller.roleAllows?.(floor.power) ?? false;
|
|
49
|
+
return (await caller.entitlements()).has(floor.entitlement);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Whether the endpoint is open to every signed-in user. What `pithy doctor` reports. */
|
|
53
|
+
export function isOpenToEverySignedInUser(floor: McpFloor): boolean {
|
|
54
|
+
return floor === "signed-in";
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The floor in one line, for `pithy doctor` and the manifest. */
|
|
58
|
+
export function floorLine(floor: McpFloor): string {
|
|
59
|
+
if (floor === "signed-in") return "open to every signed-in user";
|
|
60
|
+
if ("power" in floor) return `open only to callers whose role holds ${floor.power}`;
|
|
61
|
+
return `open only to callers holding the ${floor.entitlement} entitlement`;
|
|
62
|
+
}
|
package/src/mcp/host.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import type { ClientDiscovery } from "@better-auth/oauth-provider";
|
|
5
|
+
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
6
|
+
import type { Context } from "hono";
|
|
7
|
+
import type { AuthInstance } from "../instance/auth";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* What the auth capability lends the MCP capability composed beside it.
|
|
11
|
+
*
|
|
12
|
+
* The authorization server lives inside the auth instance — Better Auth composes a provider as a plugin, so the
|
|
13
|
+
* instance that signs a user in is the one that issues their agent's token. The MCP capability's routes need that
|
|
14
|
+
* instance, the address it resolves for this request, and the database it reads, and nothing else; this is that,
|
|
15
|
+
* and it is the only thing the MCP capability reads off auth.
|
|
16
|
+
*/
|
|
17
|
+
export interface McpHost {
|
|
18
|
+
/** This request's auth instance — the one the session middleware already built, memoized per request. */
|
|
19
|
+
instance(c: Context<PithyHonoEnv>): Promise<AuthInstance>;
|
|
20
|
+
/** The origin this request's instance runs under: the config's `baseURL`, or in `dev` the request's own host. */
|
|
21
|
+
baseURL(request: Request): string;
|
|
22
|
+
/** Where the auth handler mounts, e.g. `/auth`. The issuer is `baseURL` + this. */
|
|
23
|
+
readonly basePath: string;
|
|
24
|
+
/** The D1 binding auth's tables live in. */
|
|
25
|
+
readonly database: string;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** What the MCP capability tells auth when composed, so the instance carries the provider. */
|
|
29
|
+
export interface McpWiring {
|
|
30
|
+
/** Where the MCP endpoint mounts, e.g. `/mcp`. The resource is `baseURL` + this. */
|
|
31
|
+
readonly path: string;
|
|
32
|
+
/** The scaffolded consent screen's path. */
|
|
33
|
+
readonly consentPage: string;
|
|
34
|
+
/** How a client whose id is its metadata document's URL is resolved. One per composed `mcp()`, so its cache lasts. */
|
|
35
|
+
readonly clientDiscovery: ClientDiscovery;
|
|
36
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
function entries(values: readonly unknown[]): string[] {
|
|
5
|
+
return values
|
|
6
|
+
.filter((entry): entry is string => typeof entry === "string")
|
|
7
|
+
.map((entry) => entry.trim())
|
|
8
|
+
.filter((entry) => entry.length > 0);
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* A client's stored redirect URIs, as a list. The adapter stores them as a JSON array or comma-joined, and the
|
|
13
|
+
* connected-applications screen shows them as the one value that identifies the client, so a value that is JSON
|
|
14
|
+
* but not an array or a string names no URI rather than showing a fragment of itself as one.
|
|
15
|
+
*/
|
|
16
|
+
export function redirectList(stored: string): string[] {
|
|
17
|
+
let parsed: unknown;
|
|
18
|
+
try {
|
|
19
|
+
parsed = JSON.parse(stored);
|
|
20
|
+
} catch {
|
|
21
|
+
return entries(stored.split(","));
|
|
22
|
+
}
|
|
23
|
+
if (Array.isArray(parsed)) return entries(parsed);
|
|
24
|
+
if (typeof parsed === "string") return entries([parsed]);
|
|
25
|
+
return [];
|
|
26
|
+
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
|
|
6
|
+
/** The MCP capability's response bodies. Every route names one in its `describeRoute`. */
|
|
7
|
+
|
|
8
|
+
/** RFC 9728 protected-resource metadata: where a client finds the authorization server for this endpoint. */
|
|
9
|
+
export const ProtectedResourceMetadata = z
|
|
10
|
+
.object({
|
|
11
|
+
resource: z.string().describe("The MCP endpoint's absolute URL. Every token's audience."),
|
|
12
|
+
authorization_servers: z.array(z.string()).describe("The issuer that mints tokens for this resource."),
|
|
13
|
+
scopes_supported: z.array(z.string()).describe("The one scope this server issues, and `offline_access`."),
|
|
14
|
+
bearer_methods_supported: z.array(z.string()).describe("How a token is presented: `header` only."),
|
|
15
|
+
resource_name: z.string().describe("What this resource is, for a client to show."),
|
|
16
|
+
})
|
|
17
|
+
.describe("Protected-resource metadata (RFC 9728) for the app's MCP endpoint.");
|
|
18
|
+
export type ProtectedResourceMetadata = z.infer<typeof ProtectedResourceMetadata>;
|
|
19
|
+
|
|
20
|
+
/** RFC 8414 authorization-server metadata, relayed from the provider unchanged. */
|
|
21
|
+
export const AuthorizationServerMetadata = z
|
|
22
|
+
.record(z.string().describe("A metadata field."), z.unknown().describe("Its value."))
|
|
23
|
+
.describe("Authorization-server metadata (RFC 8414), as the composed provider publishes it.");
|
|
24
|
+
export type AuthorizationServerMetadata = z.infer<typeof AuthorizationServerMetadata>;
|
|
25
|
+
|
|
26
|
+
/** One JSON-RPC answer. */
|
|
27
|
+
export const RpcResponse = z
|
|
28
|
+
.object({
|
|
29
|
+
jsonrpc: z.literal("2.0").describe("Always `2.0`."),
|
|
30
|
+
id: z.union([z.string(), z.number()]).describe("The id of the request this answers."),
|
|
31
|
+
result: z.unknown().optional().describe("The method's result, on success."),
|
|
32
|
+
error: z
|
|
33
|
+
.object({
|
|
34
|
+
code: z.number().int().describe("The JSON-RPC error code."),
|
|
35
|
+
message: z.string().describe("What went wrong, in one sentence."),
|
|
36
|
+
})
|
|
37
|
+
.optional()
|
|
38
|
+
.describe("What went wrong, on failure."),
|
|
39
|
+
})
|
|
40
|
+
.describe("One JSON-RPC 2.0 answer.");
|
|
41
|
+
export type RpcResponse = z.infer<typeof RpcResponse>;
|
|
42
|
+
|
|
43
|
+
/** One operation a capability row lists. */
|
|
44
|
+
export const ConsentOperation = z
|
|
45
|
+
.object({
|
|
46
|
+
tool: z.string().describe("The tool's name, `<capability>_<operation>`."),
|
|
47
|
+
summary: z.string().describe("What it does, in the capability's own words."),
|
|
48
|
+
effect: z
|
|
49
|
+
.enum(["writes", "sends", "charges", "deletes"])
|
|
50
|
+
.nullable()
|
|
51
|
+
.describe("What it does beyond reading, or null for a read."),
|
|
52
|
+
})
|
|
53
|
+
.describe("One thing the client will be able to do, as you.");
|
|
54
|
+
export type ConsentOperation = z.infer<typeof ConsentOperation>;
|
|
55
|
+
|
|
56
|
+
/** One capability, as the unit of consent. */
|
|
57
|
+
export const ConsentCapability = z
|
|
58
|
+
.object({
|
|
59
|
+
capability: z.string().describe("The capability's name."),
|
|
60
|
+
operations: z
|
|
61
|
+
.array(ConsentOperation)
|
|
62
|
+
.describe("What the client will be able to do in it — only what your role allows."),
|
|
63
|
+
reachable: z.number().int().describe("How many of its operations your role allows."),
|
|
64
|
+
total: z.number().int().describe("How many operations it offers agents in all."),
|
|
65
|
+
effects: z
|
|
66
|
+
.object({
|
|
67
|
+
writes: z.number().int().describe("Operations that change data."),
|
|
68
|
+
sends: z.number().int().describe("Operations that send a message."),
|
|
69
|
+
charges: z.number().int().describe("Operations that charge money."),
|
|
70
|
+
deletes: z.number().int().describe("Operations that delete data."),
|
|
71
|
+
})
|
|
72
|
+
.describe("The reachable operations that do more than read, counted by effect."),
|
|
73
|
+
})
|
|
74
|
+
.describe("One capability the client will be able to act in, and what it can do there.");
|
|
75
|
+
export type ConsentCapability = z.infer<typeof ConsentCapability>;
|
|
76
|
+
|
|
77
|
+
/** One scope the client asked for, and what became of it. */
|
|
78
|
+
export const ConsentScope = z
|
|
79
|
+
.object({
|
|
80
|
+
scope: z.string().describe("The scope as the client asked for it."),
|
|
81
|
+
granted: z.boolean().describe("Whether approving grants it."),
|
|
82
|
+
reason: z
|
|
83
|
+
.enum(["role", "unknown"])
|
|
84
|
+
.nullable()
|
|
85
|
+
.describe(
|
|
86
|
+
"Why it is not granted: `role` when the caller's role does not reach it, `unknown` when no such permission exists. Null when it is granted.",
|
|
87
|
+
),
|
|
88
|
+
})
|
|
89
|
+
.describe("One scope the client requested.");
|
|
90
|
+
export type ConsentScope = z.infer<typeof ConsentScope>;
|
|
91
|
+
|
|
92
|
+
/** Everything the consent screen shows. */
|
|
93
|
+
export const ConsentView = z
|
|
94
|
+
.object({
|
|
95
|
+
client: z
|
|
96
|
+
.object({
|
|
97
|
+
id: z
|
|
98
|
+
.string()
|
|
99
|
+
.describe("The client's id: assigned when it registered dynamically, or the URL of its metadata document."),
|
|
100
|
+
verifiedHost: z
|
|
101
|
+
.string()
|
|
102
|
+
.nullable()
|
|
103
|
+
.optional()
|
|
104
|
+
.describe(
|
|
105
|
+
"The host that serves the client's metadata document, which is its id. Proven by fetching the document there, so it may be shown as verified. Null for a dynamically registered client, which nothing has verified.",
|
|
106
|
+
),
|
|
107
|
+
reportedName: z
|
|
108
|
+
.string()
|
|
109
|
+
.nullable()
|
|
110
|
+
.describe("The name the client gave itself. Self-asserted and never verified — show it as reported."),
|
|
111
|
+
reportedUri: z.string().nullable().describe("The homepage the client gave itself. Also unverified."),
|
|
112
|
+
redirectUri: z
|
|
113
|
+
.string()
|
|
114
|
+
.describe("Where the token goes. Enforced by the authorization server, so it is what identifies the client."),
|
|
115
|
+
})
|
|
116
|
+
.describe("The application asking for access."),
|
|
117
|
+
capabilities: z.array(ConsentCapability).describe("One row per capability you can reach. Nothing is selectable."),
|
|
118
|
+
requested: z.array(ConsentScope).describe("What the client asked for, each with what approving grants."),
|
|
119
|
+
})
|
|
120
|
+
.describe("What the consent screen shows: one decision, and its consequence.");
|
|
121
|
+
export type ConsentView = z.infer<typeof ConsentView>;
|
|
122
|
+
|
|
123
|
+
/** The answer to a consent decision. */
|
|
124
|
+
export const ConsentDecision = z
|
|
125
|
+
.object({
|
|
126
|
+
redirect: z.string().describe("Where the browser goes next: the client's redirect, carrying a code or a refusal."),
|
|
127
|
+
})
|
|
128
|
+
.describe("Where to send the browser after the decision.");
|
|
129
|
+
export type ConsentDecision = z.infer<typeof ConsentDecision>;
|
|
130
|
+
|
|
131
|
+
/** One application the caller connected. */
|
|
132
|
+
export const ConnectedApplication = z
|
|
133
|
+
.object({
|
|
134
|
+
clientId: z.string().describe("The client's id."),
|
|
135
|
+
verifiedHost: z
|
|
136
|
+
.string()
|
|
137
|
+
.nullable()
|
|
138
|
+
.optional()
|
|
139
|
+
.describe("The host that serves the client's metadata document. Null for a dynamically registered client."),
|
|
140
|
+
reportedName: z.string().nullable().describe("The name the client gave itself. Unverified."),
|
|
141
|
+
redirectUris: z.array(z.string()).describe("Where its tokens go."),
|
|
142
|
+
approvedAt: z.string().describe("When you approved it, ISO-8601."),
|
|
143
|
+
})
|
|
144
|
+
.describe("One application acting as you.");
|
|
145
|
+
export type ConnectedApplication = z.infer<typeof ConnectedApplication>;
|
|
146
|
+
|
|
147
|
+
/** Every application the caller connected. */
|
|
148
|
+
export const ConnectedApplications = z
|
|
149
|
+
.object({ applications: z.array(ConnectedApplication).describe("Newest first.") })
|
|
150
|
+
.describe("The applications acting as you, each revocable.");
|
|
151
|
+
export type ConnectedApplications = z.infer<typeof ConnectedApplications>;
|
|
152
|
+
|
|
153
|
+
/** The answer to a revocation. */
|
|
154
|
+
export const RevokedApplication = z
|
|
155
|
+
.object({ revoked: z.literal(true).describe("Always true: the client can no longer act as you.") })
|
|
156
|
+
.describe("A revoked connection.");
|
|
157
|
+
export type RevokedApplication = z.infer<typeof RevokedApplication>;
|