@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,140 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { type AuthClientOptions, type AuthResult, callAuth } from "./api";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The browser half of the MCP capability's two screens: the consent screen and connected applications.
|
|
8
|
+
*
|
|
9
|
+
* Every call goes through {@link callAuth}, the one producer of a same-origin request, with the base path pointed
|
|
10
|
+
* at the MCP endpoint instead of auth's. **Zod-free**, like everything on this side of the wire: each answer is
|
|
11
|
+
* narrowed by a hand-written guard, because this compiles into an adopter's browser bundle.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/** Where the MCP capability mounts unless configured otherwise. */
|
|
15
|
+
export const MCP_BASE_PATH = "/mcp";
|
|
16
|
+
|
|
17
|
+
/** One operation a consent row lists. */
|
|
18
|
+
export interface ConsentOperation {
|
|
19
|
+
readonly tool: string;
|
|
20
|
+
readonly summary: string;
|
|
21
|
+
readonly effect: "writes" | "sends" | "charges" | "deletes" | null;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** One capability, as the unit of consent. */
|
|
25
|
+
export interface ConsentCapability {
|
|
26
|
+
readonly capability: string;
|
|
27
|
+
readonly operations: readonly ConsentOperation[];
|
|
28
|
+
readonly reachable: number;
|
|
29
|
+
readonly total: number;
|
|
30
|
+
readonly effects: {
|
|
31
|
+
readonly writes: number;
|
|
32
|
+
readonly sends: number;
|
|
33
|
+
readonly charges: number;
|
|
34
|
+
readonly deletes: number;
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Everything the consent screen shows. See the server's `ConsentView`. */
|
|
39
|
+
export interface ConsentView {
|
|
40
|
+
readonly client: {
|
|
41
|
+
readonly id: string;
|
|
42
|
+
/** The host its metadata document proved it by. Absent or `null` when nothing verified it. */
|
|
43
|
+
readonly verifiedHost?: string | null;
|
|
44
|
+
readonly reportedName: string | null;
|
|
45
|
+
readonly reportedUri: string | null;
|
|
46
|
+
readonly redirectUri: string;
|
|
47
|
+
};
|
|
48
|
+
readonly capabilities: readonly ConsentCapability[];
|
|
49
|
+
readonly requested: readonly {
|
|
50
|
+
readonly scope: string;
|
|
51
|
+
readonly granted: boolean;
|
|
52
|
+
readonly reason: "role" | "unknown" | null;
|
|
53
|
+
}[];
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** One application acting as the user. */
|
|
57
|
+
export interface ConnectedApplication {
|
|
58
|
+
readonly clientId: string;
|
|
59
|
+
/** The host its metadata document proved it by. Absent or `null` when nothing verified it. */
|
|
60
|
+
readonly verifiedHost?: string | null;
|
|
61
|
+
readonly reportedName: string | null;
|
|
62
|
+
readonly redirectUris: readonly string[];
|
|
63
|
+
readonly approvedAt: string;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
67
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function isConsentView(value: unknown): value is ConsentView {
|
|
71
|
+
return (
|
|
72
|
+
isRecord(value) &&
|
|
73
|
+
isRecord(value.client) &&
|
|
74
|
+
typeof value.client.id === "string" &&
|
|
75
|
+
typeof value.client.redirectUri === "string" &&
|
|
76
|
+
Array.isArray(value.capabilities) &&
|
|
77
|
+
Array.isArray(value.requested)
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function isDecision(value: unknown): value is { redirect: string } {
|
|
82
|
+
return isRecord(value) && typeof value.redirect === "string";
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function isConnections(value: unknown): value is { applications: ConnectedApplication[] } {
|
|
86
|
+
return (
|
|
87
|
+
isRecord(value) &&
|
|
88
|
+
Array.isArray(value.applications) &&
|
|
89
|
+
value.applications.every((entry) => isRecord(entry) && typeof entry.clientId === "string")
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function isRevoked(value: unknown): value is { revoked: true } {
|
|
94
|
+
return isRecord(value) && value.revoked === true;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** The options a call runs with: the MCP base path, unless the caller named another. */
|
|
98
|
+
function mcpOptions(options: AuthClientOptions | undefined): AuthClientOptions {
|
|
99
|
+
return { ...options, basePath: options?.basePath ?? MCP_BASE_PATH };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** What the application asking for access will be able to do. `oauthQuery` is the screen's own query string. */
|
|
103
|
+
export function readConsent(oauthQuery: string, options?: AuthClientOptions): Promise<AuthResult<ConsentView>> {
|
|
104
|
+
const query = new URLSearchParams({ oauth_query: oauthQuery.replace(/^\?/, "") });
|
|
105
|
+
return callAuth(`/consent?${query}`, { method: "GET" }, mcpOptions(options), isConsentView);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** The one decision. Answers where to send the browser: the application's redirect, with a code or a refusal. */
|
|
109
|
+
export function decideConsent(
|
|
110
|
+
oauthQuery: string,
|
|
111
|
+
accept: boolean,
|
|
112
|
+
options?: AuthClientOptions,
|
|
113
|
+
): Promise<AuthResult<{ redirect: string }>> {
|
|
114
|
+
return callAuth(
|
|
115
|
+
"/consent",
|
|
116
|
+
{
|
|
117
|
+
method: "POST",
|
|
118
|
+
headers: { "content-type": "application/json" },
|
|
119
|
+
body: JSON.stringify({ oauth_query: oauthQuery.replace(/^\?/, ""), accept }),
|
|
120
|
+
},
|
|
121
|
+
mcpOptions(options),
|
|
122
|
+
isDecision,
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** Every application acting as the signed-in user, newest first. */
|
|
127
|
+
export async function listConnectedApplications(
|
|
128
|
+
options?: AuthClientOptions,
|
|
129
|
+
): Promise<AuthResult<readonly ConnectedApplication[]>> {
|
|
130
|
+
const result = await callAuth("/connections", { method: "GET" }, mcpOptions(options), isConnections);
|
|
131
|
+
return result.ok ? { ok: true, value: result.value.applications } : result;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Revoke one. Its next call is refused. */
|
|
135
|
+
export function revokeConnectedApplication(
|
|
136
|
+
clientId: string,
|
|
137
|
+
options?: AuthClientOptions,
|
|
138
|
+
): Promise<AuthResult<{ revoked: true }>> {
|
|
139
|
+
return callAuth(`/connections/${encodeURIComponent(clientId)}`, { method: "DELETE" }, mcpOptions(options), isRevoked);
|
|
140
|
+
}
|
package/src/data/betterAuth.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import { JsonDate, SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
5
|
import { Locale } from "@pithy-sh/core/src/i18n/locale";
|
|
6
|
+
import { pii } from "@pithy-sh/core/src/privacy/classes";
|
|
6
7
|
import { z } from "zod";
|
|
7
8
|
|
|
8
9
|
/**
|
|
@@ -30,10 +31,10 @@ const BetterAuthDate = JsonDate;
|
|
|
30
31
|
export const User = z
|
|
31
32
|
.object({
|
|
32
33
|
id: z.string().describe("Primary key. A random/UUID text id (not auto-increment) so users cannot be enumerated."),
|
|
33
|
-
name: z.string().describe("The user's display name, supplied by the provider profile or at sign-up."),
|
|
34
|
-
email: z
|
|
35
|
-
.
|
|
36
|
-
|
|
34
|
+
name: pii(z.string()).describe("The user's display name, supplied by the provider profile or at sign-up."),
|
|
35
|
+
email: pii(z.string()).describe(
|
|
36
|
+
"The user's email address. Unique across all users; the identity key for passwordless sign-in.",
|
|
37
|
+
),
|
|
37
38
|
emailVerified: SQLiteBoolean.describe(
|
|
38
39
|
"Whether the email has been verified. Stored as `0|1`; magic-link/OTP sign-in sets it true.",
|
|
39
40
|
),
|
|
@@ -72,6 +73,9 @@ export const User = z
|
|
|
72
73
|
purgeAfter: SQLiteDate.nullish().describe(
|
|
73
74
|
"When a deleted account's data may be erased — the deletion instant plus `retention.purgeAfterDays`. Null unless the account is deleted. Ms-epoch in SQLite.",
|
|
74
75
|
),
|
|
76
|
+
lastActiveAt: SQLiteDate.nullish().describe(
|
|
77
|
+
"When this account last opened a session — a sign-in or a token refresh — which a sign-out does not erase. The retention policy's class ages count inactivity from it. Stamped on every existing account when the column arrived. Ms-epoch in SQLite.",
|
|
78
|
+
),
|
|
75
79
|
})
|
|
76
80
|
.describe("A user in `pithy_auth_users` — the canonical identity every session and account hangs off.");
|
|
77
81
|
export type User = z.output<typeof User>;
|
package/src/data/kitFields.ts
CHANGED
|
@@ -53,6 +53,8 @@ const LIFECYCLE_FIELDS = {
|
|
|
53
53
|
suspendedUntil: { type: "number", required: false, input: false },
|
|
54
54
|
deletedAt: { type: "number", required: false, input: false },
|
|
55
55
|
purgeAfter: { type: "number", required: false, input: false },
|
|
56
|
+
// When the account last opened a session, stamped by `session.create.after`, never by a caller.
|
|
57
|
+
lastActiveAt: { type: "number", required: false, input: false },
|
|
56
58
|
} as const;
|
|
57
59
|
|
|
58
60
|
/**
|
package/src/data/tables.ts
CHANGED
|
@@ -8,14 +8,15 @@ import { Account, Jwks, RateLimit, Session, User, Verification } from "./betterA
|
|
|
8
8
|
import { Device } from "./device";
|
|
9
9
|
import { RotatedToken } from "./rotatedToken";
|
|
10
10
|
import { UserLifecycleEvent } from "./userLifecycle";
|
|
11
|
+
import { VerificationOutcome } from "./verificationOutcome";
|
|
11
12
|
|
|
12
13
|
/**
|
|
13
14
|
* The auth capability's table map: camelCase keys, so `CamelCasePlugin` emits the snake_case
|
|
14
15
|
* `pithy_auth_*` SQL. One source of truth shared by the capability wiring, the Better-Auth instance
|
|
15
16
|
* (whose Kysely adapter wraps this same Kysely), the device registry, and the migration.
|
|
16
17
|
*
|
|
17
|
-
* The first six tables are Better-Auth-managed; `pithyAuthDevices`, `pithyAuthRotatedTokens
|
|
18
|
-
* `pithyAuthUserLifecycle` are ours. Setting Better Auth's `modelName` to these exact camelCase keys lets the one `CamelCasePlugin`
|
|
18
|
+
* The first six tables are Better-Auth-managed; `pithyAuthDevices`, `pithyAuthRotatedTokens`,
|
|
19
|
+
* `pithyAuthUserLifecycle` and `pithyAuthVerificationOutcomes` are ours. Setting Better Auth's `modelName` to these exact camelCase keys lets the one `CamelCasePlugin`
|
|
19
20
|
* own the camelCase ↔ snake_case boundary uniformly for both Better Auth's queries and our migration DDL.
|
|
20
21
|
*/
|
|
21
22
|
export const authTables = {
|
|
@@ -28,6 +29,7 @@ export const authTables = {
|
|
|
28
29
|
pithyAuthDevices: Device,
|
|
29
30
|
pithyAuthRotatedTokens: RotatedToken,
|
|
30
31
|
pithyAuthUserLifecycle: UserLifecycleEvent,
|
|
32
|
+
pithyAuthVerificationOutcomes: VerificationOutcome,
|
|
31
33
|
};
|
|
32
34
|
export type AuthTables = typeof authTables;
|
|
33
35
|
|
|
@@ -23,9 +23,9 @@ import { z } from "zod";
|
|
|
23
23
|
|
|
24
24
|
/** What happened to the account. */
|
|
25
25
|
export const UserLifecycleAction = z
|
|
26
|
-
.enum(["suspended", "reinstated", "deleted", "restored", "purge_step", "purged"])
|
|
26
|
+
.enum(["suspended", "reinstated", "deleted", "restored", "purge_step", "purge_retained", "purge_failed", "purged"])
|
|
27
27
|
.describe(
|
|
28
|
-
"The transition: `suspended` and `reinstated`; `deleted` (by an operator, or by the account's owner) and `restored` inside the purge window; `purge_step`, one capability's rows erased during a purge, named in `step`; and `purged`, the erasure finished.",
|
|
28
|
+
"The transition: `suspended` and `reinstated`; `deleted` (by an operator, or by the account's owner) and `restored` inside the purge window; `purge_step`, one capability's rows erased during a purge, named in `step`; `purge_retained`, one capability's rows kept through a purge under the basis in `reason` (#814); `purge_failed`, the purge gave up at the step named in `step`, until the next daily pass (#823); and `purged`, the erasure finished.",
|
|
29
29
|
);
|
|
30
30
|
export type UserLifecycleAction = z.output<typeof UserLifecycleAction>;
|
|
31
31
|
|
|
@@ -70,11 +70,23 @@ export const UserLifecycleEvent = z
|
|
|
70
70
|
.string()
|
|
71
71
|
.nullable()
|
|
72
72
|
.describe(
|
|
73
|
-
"For a `purge_step` row, the capability whose rows that step erased
|
|
73
|
+
"For a `purge_step` row, the capability whose rows that step erased; for a `purge_retained` row, the capability whose rows it kept; for a `purge_failed` row, the step the purge gave up at — a capability, `mail` or `complete`. Null for every other action.",
|
|
74
74
|
),
|
|
75
75
|
notify: SQLiteBoolean.nullable().describe(
|
|
76
76
|
"For a hard deletion's `deleted` row, whether the purge sends the deletion-complete mail — false when the deletion asked for none. Null for every other row, and for a hard deletion that did not say. The purge reads it, so a purge the daily pass starts keeps the choice (#622).",
|
|
77
77
|
),
|
|
78
|
+
mode: z
|
|
79
|
+
.enum(["soft", "hard"])
|
|
80
|
+
.nullable()
|
|
81
|
+
.default(null)
|
|
82
|
+
.describe(
|
|
83
|
+
"For a `deleted` row, how the deletion was asked for: `soft` with a window, `hard` with none — a hard deletion bringing a soft one forward writes its own `hard` row. Null for every other row, and for a deletion recorded before `0007_erasure_record` (#823).",
|
|
84
|
+
),
|
|
85
|
+
purgeAfter: SQLiteDate.nullable()
|
|
86
|
+
.default(null)
|
|
87
|
+
.describe(
|
|
88
|
+
"For a `deleted` row, when its purge comes due — kept here because the purge erases the account's own column. Null for every other row, and before `0007_erasure_record` (#823). Ms-epoch in SQLite.",
|
|
89
|
+
),
|
|
78
90
|
createdAt: SQLiteDate.describe("When the transition happened. Ms-epoch in SQLite; a `Date` in app code."),
|
|
79
91
|
})
|
|
80
92
|
.describe(
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* `pithy_auth_verification_outcomes` — the verification ledger (#829): one row per sign-in link or code auth
|
|
9
|
+
* issued, and whether it was used.
|
|
10
|
+
*
|
|
11
|
+
* **Why a ledger, and not a read of `pithy_auth_verifications`.** Better Auth consumes a verification row on its
|
|
12
|
+
* first use and deletes it, so a used link leaves nothing behind, and an unused one looks exactly like one still
|
|
13
|
+
* waiting until the cleanup on some later read takes it. "How many sign-ins failed because mail did not land"
|
|
14
|
+
* needs both halves, so auth writes its own record: when it issues, and again when the link or code is used.
|
|
15
|
+
*
|
|
16
|
+
* **Never the token, never the address.** The row names the verification by its row id, the person by their user
|
|
17
|
+
* id where one exists, and the mail by its `pithy_email_jobs` id — which is where the address already lives,
|
|
18
|
+
* under email's own retention. A sign-up has no user when its link is sent, so its row joins to its mail by the
|
|
19
|
+
* job id alone and gains the user id when the link is used and the account exists.
|
|
20
|
+
*
|
|
21
|
+
* **No foreign key, to the user or to the job.** The two live in different capabilities' tables, and a purge of
|
|
22
|
+
* the account erases its rows here by user id (`../purge/contribution.ts`).
|
|
23
|
+
*
|
|
24
|
+
* Written by the kit through its own Kysely, so its dates take the house ms-epoch `SQLiteDate`.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** What was issued. */
|
|
28
|
+
export const VerificationType = z
|
|
29
|
+
.enum(["magic_link", "otp"])
|
|
30
|
+
.describe(
|
|
31
|
+
"What was issued: `magic_link`, a sign-in link; `otp`, a one-time sign-in code. The only two auth sends — it composes no password, so no reset, and no separate email-verification mail.",
|
|
32
|
+
);
|
|
33
|
+
export type VerificationType = z.output<typeof VerificationType>;
|
|
34
|
+
|
|
35
|
+
/** One issued link or code, as stored. */
|
|
36
|
+
export const VerificationOutcome = z
|
|
37
|
+
.object({
|
|
38
|
+
id: z
|
|
39
|
+
.number()
|
|
40
|
+
.int()
|
|
41
|
+
.describe("Primary key. Auto-incrementing, so two rows issued in the same millisecond keep their order."),
|
|
42
|
+
verificationId: z
|
|
43
|
+
.string()
|
|
44
|
+
.describe(
|
|
45
|
+
"The `pithy_auth_verifications` row that carries this link or code. A wrong code is re-issued under a new row with the same expiry, and this follows it. Indexed.",
|
|
46
|
+
),
|
|
47
|
+
type: VerificationType.describe("What was issued."),
|
|
48
|
+
userId: z
|
|
49
|
+
.string()
|
|
50
|
+
.nullable()
|
|
51
|
+
.describe(
|
|
52
|
+
"The account it signs in to, when one existed at issue or was created by its use. Null for a sign-up nobody completed. Indexed, so a purge finds the account's rows.",
|
|
53
|
+
),
|
|
54
|
+
emailJobId: z
|
|
55
|
+
.string()
|
|
56
|
+
.nullable()
|
|
57
|
+
.describe(
|
|
58
|
+
"The `pithy_email_jobs` row that carried it — how a reader joins it to a bounce, a deferral or a suppression. Null when the email seam failed and nothing was queued.",
|
|
59
|
+
),
|
|
60
|
+
issuedAt: SQLiteDate.describe("When it was issued. Ms-epoch in SQLite; a `Date` in app code."),
|
|
61
|
+
expiresAt: SQLiteDate.describe("When it stops working, used or not. Ms-epoch in SQLite."),
|
|
62
|
+
usedAt: SQLiteDate.nullable().describe(
|
|
63
|
+
"When it was used to sign in, or null while it has not been. Ms-epoch in SQLite.",
|
|
64
|
+
),
|
|
65
|
+
})
|
|
66
|
+
.describe(
|
|
67
|
+
"One sign-in link or code in `pithy_auth_verification_outcomes`: what it was, whose, the mail that carried it, and when it was issued, expires and was used. Never the token or the address.",
|
|
68
|
+
);
|
|
69
|
+
export type VerificationOutcome = z.output<typeof VerificationOutcome>;
|
|
70
|
+
|
|
71
|
+
/** Where an issued link or code stands at a moment: used, expired unused, or still pending. */
|
|
72
|
+
export const VerificationState = z
|
|
73
|
+
.enum(["used", "expired", "pending"])
|
|
74
|
+
.describe(
|
|
75
|
+
"Where it stands: `used`, it signed somebody in; `expired`, it ran out unused; `pending`, it is unused and still works.",
|
|
76
|
+
);
|
|
77
|
+
export type VerificationState = z.output<typeof VerificationState>;
|
|
78
|
+
|
|
79
|
+
/** Where one row stands at `now`. Used wins over expiry: a link used a second before it ran out was used. */
|
|
80
|
+
export function verificationStateAt(
|
|
81
|
+
row: Pick<VerificationOutcome, "expiresAt" | "usedAt">,
|
|
82
|
+
now: Date,
|
|
83
|
+
): VerificationState {
|
|
84
|
+
if (row.usedAt !== null) return "used";
|
|
85
|
+
return row.expiresAt.getTime() <= now.getTime() ? "expired" : "pending";
|
|
86
|
+
}
|
package/src/email/send.ts
CHANGED
|
@@ -98,7 +98,7 @@ export function makeSendAuthEmail(
|
|
|
98
98
|
*/
|
|
99
99
|
function deliveryOf(result: EnqueueResult): AuthEmailDelivery {
|
|
100
100
|
if (result.status === "suppressed") {
|
|
101
|
-
return { delivery: "withheld", reason: result.suppressionReason ?? result.status };
|
|
101
|
+
return { delivery: "withheld", reason: result.suppressionReason ?? result.status, jobId: result.jobId };
|
|
102
102
|
}
|
|
103
|
-
return { delivery: "queued" };
|
|
103
|
+
return { delivery: "queued", jobId: result.jobId };
|
|
104
104
|
}
|
package/src/http/adminRoutes.ts
CHANGED
|
@@ -28,6 +28,7 @@ import { correlation, emitControlPlaneAction } from "../audit/emit";
|
|
|
28
28
|
import type { AuthWiring } from "../capability";
|
|
29
29
|
import { authDatabase } from "../data/tables";
|
|
30
30
|
import { deleteDevice, deviceSessionTokens } from "../device/registry";
|
|
31
|
+
import { listVerificationOutcomes, resolveVerificationWindow, verificationCounts } from "../ledger/read";
|
|
31
32
|
import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audited";
|
|
32
33
|
import { MAX_REASON } from "../lifecycle/reason";
|
|
33
34
|
import { lifecycleDeps } from "../lifecycle/request";
|
|
@@ -35,6 +36,7 @@ import {
|
|
|
35
36
|
type DeleteTransition,
|
|
36
37
|
deleteUser,
|
|
37
38
|
type LifecycleActor,
|
|
39
|
+
purgeAddress,
|
|
38
40
|
reinstateUser,
|
|
39
41
|
requirePresent,
|
|
40
42
|
restoreUser,
|
|
@@ -51,6 +53,7 @@ import {
|
|
|
51
53
|
AUTH_USERS_LOGOUT_SCOPE,
|
|
52
54
|
AUTH_USERS_READ_SCOPE,
|
|
53
55
|
AUTH_USERS_SUSPEND_SCOPE,
|
|
56
|
+
AUTH_VERIFICATIONS_READ_SCOPE,
|
|
54
57
|
} from "./guards";
|
|
55
58
|
import { getAuthInstance, resolveDb } from "./resolve";
|
|
56
59
|
import {
|
|
@@ -64,12 +67,14 @@ import {
|
|
|
64
67
|
AdminUserRestoreResponse,
|
|
65
68
|
AdminUserSuspendResponse,
|
|
66
69
|
AdminUsersResponse,
|
|
70
|
+
AdminVerificationsResponse,
|
|
67
71
|
} from "./responses";
|
|
68
72
|
import {
|
|
69
73
|
DeleteUserBody,
|
|
70
74
|
ExportUserQuery,
|
|
71
75
|
ListDevicesQuery,
|
|
72
76
|
ListUsersQuery,
|
|
77
|
+
ListVerificationsQuery,
|
|
73
78
|
ReinstateUserBody,
|
|
74
79
|
RestoreUserBody,
|
|
75
80
|
RevokeDeviceBody,
|
|
@@ -87,6 +92,7 @@ import {
|
|
|
87
92
|
sessionView,
|
|
88
93
|
suspensionView,
|
|
89
94
|
userView,
|
|
95
|
+
verificationView,
|
|
90
96
|
} from "./views";
|
|
91
97
|
|
|
92
98
|
type Ctx = Context<PithyHonoEnv>;
|
|
@@ -98,6 +104,7 @@ type Ctx = Context<PithyHonoEnv>;
|
|
|
98
104
|
* GET {base}/admin/users auth:users:read query: ListUsersQuery
|
|
99
105
|
* GET {base}/admin/users/:userId auth:users:read param: UserIdParam
|
|
100
106
|
* GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
|
|
107
|
+
* GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
|
|
101
108
|
* POST {base}/admin/sessions/revoke auth:sessions:revoke json: RevokeSessionBody
|
|
102
109
|
* POST {base}/admin/users/:userId/sessions/revoke auth:users:logout param: UserIdParam
|
|
103
110
|
* POST {base}/admin/users/:userId/devices/revoke auth:devices:revoke param + json
|
|
@@ -371,7 +378,12 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
|
|
|
371
378
|
// makes an exfiltration pattern visible; the string itself adds nothing to that.
|
|
372
379
|
metadata: { searched: query.search !== undefined, returned: page.items.length },
|
|
373
380
|
});
|
|
374
|
-
|
|
381
|
+
// One instant for the page, so every user on it is judged at the same moment.
|
|
382
|
+
const now = new Date();
|
|
383
|
+
return c.json({
|
|
384
|
+
users: page.items.map((user) => userView(user, now)),
|
|
385
|
+
nextCursor: page.nextCursor,
|
|
386
|
+
} satisfies AdminUsersResponse);
|
|
375
387
|
},
|
|
376
388
|
);
|
|
377
389
|
|
|
@@ -423,7 +435,7 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
|
|
|
423
435
|
});
|
|
424
436
|
|
|
425
437
|
return c.json({
|
|
426
|
-
user: userView(user),
|
|
438
|
+
user: userView(user, new Date()),
|
|
427
439
|
providers,
|
|
428
440
|
sessions,
|
|
429
441
|
devices,
|
|
@@ -461,6 +473,56 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
|
|
|
461
473
|
},
|
|
462
474
|
);
|
|
463
475
|
|
|
476
|
+
app.get(
|
|
477
|
+
`${base}/admin/verifications`,
|
|
478
|
+
describeRoute({
|
|
479
|
+
summary:
|
|
480
|
+
"Count the sign-in links and codes sent over a window by type and state, and page through them, newest first.",
|
|
481
|
+
verification: "control-plane",
|
|
482
|
+
scopes: [AUTH_VERIFICATIONS_READ_SCOPE],
|
|
483
|
+
responses: { 200: AdminVerificationsResponse },
|
|
484
|
+
}),
|
|
485
|
+
requireControlPlane(AUTH_VERIFICATIONS_READ_SCOPE),
|
|
486
|
+
validate("query", ListVerificationsQuery),
|
|
487
|
+
async (c) => {
|
|
488
|
+
const query = c.req.valid("query");
|
|
489
|
+
const caller = controlPlaneCaller(c);
|
|
490
|
+
// One `now` for both reads, so a row the counts call pending is listed as pending.
|
|
491
|
+
const now = new Date();
|
|
492
|
+
const window = resolveVerificationWindow(query, now);
|
|
493
|
+
const database = db(c, wiring);
|
|
494
|
+
const [counts, page] = await Promise.all([
|
|
495
|
+
verificationCounts(database, window, now),
|
|
496
|
+
listVerificationOutcomes(database, {
|
|
497
|
+
window,
|
|
498
|
+
now,
|
|
499
|
+
type: query.type,
|
|
500
|
+
state: query.state,
|
|
501
|
+
cursor: query.cursor,
|
|
502
|
+
limit: query.limit,
|
|
503
|
+
}),
|
|
504
|
+
]);
|
|
505
|
+
await emitControlPlaneAction(c.var.emit, {
|
|
506
|
+
action: AuthAuditActions.adminVerificationsListed,
|
|
507
|
+
subject: caller.subject,
|
|
508
|
+
connectionId: caller.connectionId,
|
|
509
|
+
resourceType: "verification",
|
|
510
|
+
...context(c),
|
|
511
|
+
metadata: {
|
|
512
|
+
since: window.since.toISOString(),
|
|
513
|
+
until: window.until.toISOString(),
|
|
514
|
+
returned: page.items.length,
|
|
515
|
+
},
|
|
516
|
+
});
|
|
517
|
+
return c.json({
|
|
518
|
+
window: { since: window.since.toISOString(), until: window.until.toISOString() },
|
|
519
|
+
counts,
|
|
520
|
+
verifications: page.items.map((row) => verificationView(row, now)),
|
|
521
|
+
nextCursor: page.nextCursor,
|
|
522
|
+
} satisfies AdminVerificationsResponse);
|
|
523
|
+
},
|
|
524
|
+
);
|
|
525
|
+
|
|
464
526
|
app.post(
|
|
465
527
|
`${base}/admin/sessions/revoke`,
|
|
466
528
|
describeRoute({
|
|
@@ -769,10 +831,13 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
|
|
|
769
831
|
c.var.emit,
|
|
770
832
|
{ action: AuthAuditActions.adminUserExported, ...call.audit },
|
|
771
833
|
async () => {
|
|
772
|
-
|
|
834
|
+
const database = db(c, wiring);
|
|
835
|
+
await requirePresent(database, userId);
|
|
773
836
|
return purgeExports(wiring.purgeSteps ?? [], {
|
|
774
837
|
subject: { type: "user", id: userId },
|
|
775
838
|
env: c.env as Record<string, unknown>,
|
|
839
|
+
// A capability holding rows by address — a suppression, a tester's membership — reads it here (#814).
|
|
840
|
+
address: () => purgeAddress(database, userId),
|
|
776
841
|
});
|
|
777
842
|
},
|
|
778
843
|
() => false,
|
package/src/http/csrf.ts
CHANGED
|
@@ -6,6 +6,7 @@ import { type AmbientEnv, ambientEnv } from "@pithy-sh/core/src/env/ambient";
|
|
|
6
6
|
import { ForbiddenError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
7
|
import type { SameOriginGate } from "@pithy-sh/core/src/http/sameOrigin";
|
|
8
8
|
import type { AuthWiring } from "../capability";
|
|
9
|
+
import { dispatchedAuth } from "../mcp/dispatch";
|
|
9
10
|
import { baseURLResolver, type ResolveBaseURL } from "./baseUrl";
|
|
10
11
|
|
|
11
12
|
/**
|
|
@@ -50,7 +51,9 @@ function sameOriginGate(allowedOrigins: readonly string[], resolveBaseURL: Resol
|
|
|
50
51
|
const allowed = new Set(allowedOrigins);
|
|
51
52
|
return async (c, next) => {
|
|
52
53
|
// A bearer request has no ambient credential to forge — CSRF-exempt.
|
|
53
|
-
|
|
54
|
+
// Nor does a tool call the MCP endpoint dispatched in process: it carries no credential at all, and the
|
|
55
|
+
// bearer token it was verified against was checked before it was built.
|
|
56
|
+
if (c.req.raw.headers.has("authorization") || dispatchedAuth(c.req.raw) !== undefined) {
|
|
54
57
|
await next();
|
|
55
58
|
return;
|
|
56
59
|
}
|