@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,53 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* `pithy_auth_verification_outcomes` — the verification ledger (#829): one row per sign-in link or code auth
|
|
6
|
+
* issued, and whether it was used.
|
|
7
|
+
*
|
|
8
|
+
* **Why a ledger, and not a read of `pithy_auth_verifications`.** Better Auth consumes a verification row on its
|
|
9
|
+
* first use and deletes it, so a used link leaves nothing behind, and an unused one looks exactly like one still
|
|
10
|
+
* waiting until the cleanup on some later read takes it. "How many sign-ins failed because mail did not land"
|
|
11
|
+
* needs both halves, so auth writes its own record: when it issues, and again when the link or code is used.
|
|
12
|
+
*
|
|
13
|
+
* **Never the token, never the address.** The row names the verification by its row id, the person by their user
|
|
14
|
+
* id where one exists, and the mail by its `pithy_email_jobs` id — which is where the address already lives,
|
|
15
|
+
* 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
|
|
16
|
+
* job id alone and gains the user id when the link is used and the account exists.
|
|
17
|
+
*
|
|
18
|
+
* **No foreign key, to the user or to the job.** The two live in different capabilities' tables, and a purge of
|
|
19
|
+
* the account erases its rows here by user id (`../purge/contribution.ts`).
|
|
20
|
+
*
|
|
21
|
+
* Written by the kit through its own Kysely, so its dates take the house ms-epoch `SQLiteDate`.
|
|
22
|
+
*/
|
|
23
|
+
/** What was issued. */
|
|
24
|
+
export declare const VerificationType: z.ZodEnum<{
|
|
25
|
+
magic_link: "magic_link";
|
|
26
|
+
otp: "otp";
|
|
27
|
+
}>;
|
|
28
|
+
export type VerificationType = z.output<typeof VerificationType>;
|
|
29
|
+
/** One issued link or code, as stored. */
|
|
30
|
+
export declare const VerificationOutcome: z.ZodObject<{
|
|
31
|
+
id: z.ZodNumber;
|
|
32
|
+
verificationId: z.ZodString;
|
|
33
|
+
type: z.ZodEnum<{
|
|
34
|
+
magic_link: "magic_link";
|
|
35
|
+
otp: "otp";
|
|
36
|
+
}>;
|
|
37
|
+
userId: z.ZodNullable<z.ZodString>;
|
|
38
|
+
emailJobId: z.ZodNullable<z.ZodString>;
|
|
39
|
+
issuedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
|
|
40
|
+
expiresAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
|
|
41
|
+
usedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
|
|
42
|
+
}, z.core.$strip>;
|
|
43
|
+
export type VerificationOutcome = z.output<typeof VerificationOutcome>;
|
|
44
|
+
/** Where an issued link or code stands at a moment: used, expired unused, or still pending. */
|
|
45
|
+
export declare const VerificationState: z.ZodEnum<{
|
|
46
|
+
expired: "expired";
|
|
47
|
+
pending: "pending";
|
|
48
|
+
used: "used";
|
|
49
|
+
}>;
|
|
50
|
+
export type VerificationState = z.output<typeof VerificationState>;
|
|
51
|
+
/** Where one row stands at `now`. Used wins over expiry: a link used a second before it ran out was used. */
|
|
52
|
+
export declare function verificationStateAt(row: Pick<VerificationOutcome, "expiresAt" | "usedAt">, now: Date): VerificationState;
|
|
53
|
+
//# sourceMappingURL=verificationOutcome.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"verificationOutcome.d.ts","sourceRoot":"","sources":["../../src/data/verificationOutcome.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uBAAuB;AACvB,eAAO,MAAM,gBAAgB;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,0CAA0C;AAC1C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBAgC7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB;;;;EAI3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,6GAA6G;AAC7G,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,QAAQ,CAAC,EACtD,GAAG,EAAE,IAAI,GACR,iBAAiB,CAGnB"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
|
+
//#region src/data/verificationOutcome.ts
|
|
6
|
+
/**
|
|
7
|
+
* `pithy_auth_verification_outcomes` — the verification ledger (#829): one row per sign-in link or code auth
|
|
8
|
+
* issued, and whether it was used.
|
|
9
|
+
*
|
|
10
|
+
* **Why a ledger, and not a read of `pithy_auth_verifications`.** Better Auth consumes a verification row on its
|
|
11
|
+
* first use and deletes it, so a used link leaves nothing behind, and an unused one looks exactly like one still
|
|
12
|
+
* waiting until the cleanup on some later read takes it. "How many sign-ins failed because mail did not land"
|
|
13
|
+
* needs both halves, so auth writes its own record: when it issues, and again when the link or code is used.
|
|
14
|
+
*
|
|
15
|
+
* **Never the token, never the address.** The row names the verification by its row id, the person by their user
|
|
16
|
+
* id where one exists, and the mail by its `pithy_email_jobs` id — which is where the address already lives,
|
|
17
|
+
* 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
|
|
18
|
+
* job id alone and gains the user id when the link is used and the account exists.
|
|
19
|
+
*
|
|
20
|
+
* **No foreign key, to the user or to the job.** The two live in different capabilities' tables, and a purge of
|
|
21
|
+
* the account erases its rows here by user id (`../purge/contribution.ts`).
|
|
22
|
+
*
|
|
23
|
+
* Written by the kit through its own Kysely, so its dates take the house ms-epoch `SQLiteDate`.
|
|
24
|
+
*/
|
|
25
|
+
/** What was issued. */
|
|
26
|
+
const VerificationType = z.enum(["magic_link", "otp"]).describe("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.");
|
|
27
|
+
/** One issued link or code, as stored. */
|
|
28
|
+
const VerificationOutcome = z.object({
|
|
29
|
+
id: z.number().int().describe("Primary key. Auto-incrementing, so two rows issued in the same millisecond keep their order."),
|
|
30
|
+
verificationId: z.string().describe("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."),
|
|
31
|
+
type: VerificationType.describe("What was issued."),
|
|
32
|
+
userId: z.string().nullable().describe("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."),
|
|
33
|
+
emailJobId: z.string().nullable().describe("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."),
|
|
34
|
+
issuedAt: SQLiteDate.describe("When it was issued. Ms-epoch in SQLite; a `Date` in app code."),
|
|
35
|
+
expiresAt: SQLiteDate.describe("When it stops working, used or not. Ms-epoch in SQLite."),
|
|
36
|
+
usedAt: SQLiteDate.nullable().describe("When it was used to sign in, or null while it has not been. Ms-epoch in SQLite.")
|
|
37
|
+
}).describe("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.");
|
|
38
|
+
/** Where an issued link or code stands at a moment: used, expired unused, or still pending. */
|
|
39
|
+
const VerificationState = z.enum([
|
|
40
|
+
"used",
|
|
41
|
+
"expired",
|
|
42
|
+
"pending"
|
|
43
|
+
]).describe("Where it stands: `used`, it signed somebody in; `expired`, it ran out unused; `pending`, it is unused and still works.");
|
|
44
|
+
/** Where one row stands at `now`. Used wins over expiry: a link used a second before it ran out was used. */
|
|
45
|
+
function verificationStateAt(row, now) {
|
|
46
|
+
if (row.usedAt !== null) return "used";
|
|
47
|
+
return row.expiresAt.getTime() <= now.getTime() ? "expired" : "pending";
|
|
48
|
+
}
|
|
49
|
+
//#endregion
|
|
50
|
+
export { VerificationOutcome, VerificationState, VerificationType, verificationStateAt };
|
package/dist/email/send.js
CHANGED
|
@@ -64,9 +64,13 @@ function makeSendAuthEmail(enqueue, expiresMinutes, localeFor) {
|
|
|
64
64
|
function deliveryOf(result) {
|
|
65
65
|
if (result.status === "suppressed") return {
|
|
66
66
|
delivery: "withheld",
|
|
67
|
-
reason: result.suppressionReason ?? result.status
|
|
67
|
+
reason: result.suppressionReason ?? result.status,
|
|
68
|
+
jobId: result.jobId
|
|
69
|
+
};
|
|
70
|
+
return {
|
|
71
|
+
delivery: "queued",
|
|
72
|
+
jobId: result.jobId
|
|
68
73
|
};
|
|
69
|
-
return { delivery: "queued" };
|
|
70
74
|
}
|
|
71
75
|
//#endregion
|
|
72
76
|
export { makeSendAuthEmail };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AA8ThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAmgB7F"}
|
package/dist/http/adminRoutes.js
CHANGED
|
@@ -1,21 +1,22 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { authDatabase } from "../data/tables.js";
|
|
4
3
|
import { AuthAuditActions } from "../audit/actions.js";
|
|
4
|
+
import { authDatabase } from "../data/tables.js";
|
|
5
5
|
import { correlation, emitControlPlaneAction } from "../audit/emit.js";
|
|
6
6
|
import { deleteDevice, deviceSessionTokens } from "../device/registry.js";
|
|
7
7
|
import { getAuthInstance, resolveDb } from "./resolve.js";
|
|
8
|
-
import { AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE } from "./guards.js";
|
|
8
|
+
import { AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, AUTH_VERIFICATIONS_READ_SCOPE } from "./guards.js";
|
|
9
9
|
import { findSessionById, getUser, listDeviceRegistry, listUserDevices, listUserSessions, listUsers, userProviders, userSessionTokens } from "../admin/users.js";
|
|
10
10
|
import { lifecycleDeps } from "../lifecycle/request.js";
|
|
11
11
|
import "../lifecycle/reason.js";
|
|
12
|
-
import { deleteUser, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
|
|
12
|
+
import { deleteUser, purgeAddress, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
|
|
13
|
+
import { listVerificationOutcomes, resolveVerificationWindow, verificationCounts } from "../ledger/read.js";
|
|
13
14
|
import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audited.js";
|
|
14
15
|
import { AUTH_PURGE_BINDING } from "../purge/specs.js";
|
|
15
16
|
import { startPurgeInstance } from "../purge/start.js";
|
|
16
|
-
import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserDeleteResponse, AdminUserExportResponse, AdminUserReinstateResponse, AdminUserResponse, AdminUserRestoreResponse, AdminUserSuspendResponse, AdminUsersResponse } from "./responses.js";
|
|
17
|
-
import { DeleteUserBody, ExportUserQuery, ListDevicesQuery, ListUsersQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SuspendUserBody, UserIdParam } from "./schemas.js";
|
|
18
|
-
import { deletionView, deviceView, exportView, reinstatementView, restorationView, sessionView, suspensionView, userView } from "./views.js";
|
|
17
|
+
import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserDeleteResponse, AdminUserExportResponse, AdminUserReinstateResponse, AdminUserResponse, AdminUserRestoreResponse, AdminUserSuspendResponse, AdminUsersResponse, AdminVerificationsResponse } from "./responses.js";
|
|
18
|
+
import { DeleteUserBody, ExportUserQuery, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SuspendUserBody, UserIdParam } from "./schemas.js";
|
|
19
|
+
import { deletionView, deviceView, exportView, reinstatementView, restorationView, sessionView, suspensionView, userView, verificationView } from "./views.js";
|
|
19
20
|
import { purgeExports } from "@pithy-sh/core/src/capability/purge";
|
|
20
21
|
import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
21
22
|
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
@@ -31,6 +32,7 @@ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
|
|
|
31
32
|
* GET {base}/admin/users auth:users:read query: ListUsersQuery
|
|
32
33
|
* GET {base}/admin/users/:userId auth:users:read param: UserIdParam
|
|
33
34
|
* GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
|
|
35
|
+
* GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
|
|
34
36
|
* POST {base}/admin/sessions/revoke auth:sessions:revoke json: RevokeSessionBody
|
|
35
37
|
* POST {base}/admin/users/:userId/sessions/revoke auth:users:logout param: UserIdParam
|
|
36
38
|
* POST {base}/admin/users/:userId/devices/revoke auth:devices:revoke param + json
|
|
@@ -281,8 +283,9 @@ function registerAuthAdminRoutes(wiring) {
|
|
|
281
283
|
returned: page.items.length
|
|
282
284
|
}
|
|
283
285
|
});
|
|
286
|
+
const now = /* @__PURE__ */ new Date();
|
|
284
287
|
return c.json({
|
|
285
|
-
users: page.items.map(userView),
|
|
288
|
+
users: page.items.map((user) => userView(user, now)),
|
|
286
289
|
nextCursor: page.nextCursor
|
|
287
290
|
});
|
|
288
291
|
});
|
|
@@ -318,7 +321,7 @@ function registerAuthAdminRoutes(wiring) {
|
|
|
318
321
|
}
|
|
319
322
|
});
|
|
320
323
|
return c.json({
|
|
321
|
-
user: userView(user),
|
|
324
|
+
user: userView(user, /* @__PURE__ */ new Date()),
|
|
322
325
|
providers,
|
|
323
326
|
sessions,
|
|
324
327
|
devices
|
|
@@ -350,6 +353,47 @@ function registerAuthAdminRoutes(wiring) {
|
|
|
350
353
|
nextCursor: page.nextCursor
|
|
351
354
|
});
|
|
352
355
|
});
|
|
356
|
+
app.get(`${base}/admin/verifications`, describeRoute({
|
|
357
|
+
summary: "Count the sign-in links and codes sent over a window by type and state, and page through them, newest first.",
|
|
358
|
+
verification: "control-plane",
|
|
359
|
+
scopes: [AUTH_VERIFICATIONS_READ_SCOPE],
|
|
360
|
+
responses: { 200: AdminVerificationsResponse }
|
|
361
|
+
}), requireControlPlane(AUTH_VERIFICATIONS_READ_SCOPE), validate("query", ListVerificationsQuery), async (c) => {
|
|
362
|
+
const query = c.req.valid("query");
|
|
363
|
+
const caller = controlPlaneCaller(c);
|
|
364
|
+
const now = /* @__PURE__ */ new Date();
|
|
365
|
+
const window = resolveVerificationWindow(query, now);
|
|
366
|
+
const database = db(c, wiring);
|
|
367
|
+
const [counts, page] = await Promise.all([verificationCounts(database, window, now), listVerificationOutcomes(database, {
|
|
368
|
+
window,
|
|
369
|
+
now,
|
|
370
|
+
type: query.type,
|
|
371
|
+
state: query.state,
|
|
372
|
+
cursor: query.cursor,
|
|
373
|
+
limit: query.limit
|
|
374
|
+
})]);
|
|
375
|
+
await emitControlPlaneAction(c.var.emit, {
|
|
376
|
+
action: AuthAuditActions.adminVerificationsListed,
|
|
377
|
+
subject: caller.subject,
|
|
378
|
+
connectionId: caller.connectionId,
|
|
379
|
+
resourceType: "verification",
|
|
380
|
+
...context(c),
|
|
381
|
+
metadata: {
|
|
382
|
+
since: window.since.toISOString(),
|
|
383
|
+
until: window.until.toISOString(),
|
|
384
|
+
returned: page.items.length
|
|
385
|
+
}
|
|
386
|
+
});
|
|
387
|
+
return c.json({
|
|
388
|
+
window: {
|
|
389
|
+
since: window.since.toISOString(),
|
|
390
|
+
until: window.until.toISOString()
|
|
391
|
+
},
|
|
392
|
+
counts,
|
|
393
|
+
verifications: page.items.map((row) => verificationView(row, now)),
|
|
394
|
+
nextCursor: page.nextCursor
|
|
395
|
+
});
|
|
396
|
+
});
|
|
353
397
|
app.post(`${base}/admin/sessions/revoke`, describeRoute({
|
|
354
398
|
summary: "Revoke one session by its id.",
|
|
355
399
|
verification: "control-plane",
|
|
@@ -542,13 +586,15 @@ function registerAuthAdminRoutes(wiring) {
|
|
|
542
586
|
action: AuthAuditActions.adminUserExported,
|
|
543
587
|
...call.audit
|
|
544
588
|
}, async () => {
|
|
545
|
-
|
|
589
|
+
const database = db(c, wiring);
|
|
590
|
+
await requirePresent(database, userId);
|
|
546
591
|
return purgeExports(wiring.purgeSteps ?? [], {
|
|
547
592
|
subject: {
|
|
548
593
|
type: "user",
|
|
549
594
|
id: userId
|
|
550
595
|
},
|
|
551
|
-
env: c.env
|
|
596
|
+
env: c.env,
|
|
597
|
+
address: () => purgeAddress(database, userId)
|
|
552
598
|
});
|
|
553
599
|
}, () => false);
|
|
554
600
|
await emitControlPlaneAction(c.var.emit, {
|
package/dist/http/csrf.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/http/csrf.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/http/csrf.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,GAAE,UAAyB,GAAG,eAAe,CAWrG"}
|
package/dist/http/csrf.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { baseURLResolver } from "./baseUrl.js";
|
|
4
|
+
import { dispatchedAuth } from "../mcp/dispatch.js";
|
|
4
5
|
import { ForbiddenError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
6
|
import { ambientEnv } from "@pithy-sh/core/src/env/ambient";
|
|
6
7
|
//#region src/http/csrf.ts
|
|
@@ -43,7 +44,7 @@ function allowedOrigins(baseURL, trustedOrigins) {
|
|
|
43
44
|
function sameOriginGate(allowedOrigins, resolveBaseURL) {
|
|
44
45
|
const allowed = new Set(allowedOrigins);
|
|
45
46
|
return async (c, next) => {
|
|
46
|
-
if (c.req.raw.headers.has("authorization")) {
|
|
47
|
+
if (c.req.raw.headers.has("authorization") || dispatchedAuth(c.req.raw) !== void 0) {
|
|
47
48
|
await next();
|
|
48
49
|
return;
|
|
49
50
|
}
|
package/dist/http/guards.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import type {
|
|
3
|
+
import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
|
|
4
4
|
import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
|
|
5
5
|
/**
|
|
6
6
|
* Auth's control-plane scopes, and the admin surface a manifest advertises.
|
|
@@ -27,7 +27,7 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
27
27
|
* every legitimate management call, permanently, and **no credential could fix it** — there is no user
|
|
28
28
|
* to sign in as. `controlPlaneIsolation.workers.test.ts` pins both directions of that separation.
|
|
29
29
|
*
|
|
30
|
-
* ##
|
|
30
|
+
* ## Nine scopes, because these are nine different blast radii
|
|
31
31
|
*
|
|
32
32
|
* The temptation is one `auth:admin` flag, and on this capability it is the most dangerous version of
|
|
33
33
|
* that mistake. **Reading a user is a privacy operation; revoking their sessions is an availability
|
|
@@ -85,31 +85,35 @@ export declare const AUTH_USERS_LOGOUT_SCOPE: ControlPlaneScope;
|
|
|
85
85
|
*/
|
|
86
86
|
export declare const AUTH_DEVICES_REVOKE_SCOPE: ControlPlaneScope;
|
|
87
87
|
/**
|
|
88
|
-
* Suspend an account and reinstate it
|
|
88
|
+
* Suspend an account and reinstate it: `POST {base}/admin/users/:userId/suspend` and `/reinstate`. Ending somebody's access is an availability
|
|
89
89
|
* operation on one person, and reversible — which is what separates it from deleting them, and why it is
|
|
90
90
|
* granted apart from both reading them and erasing them.
|
|
91
91
|
*/
|
|
92
92
|
export declare const AUTH_USERS_SUSPEND_SCOPE: ControlPlaneScope;
|
|
93
93
|
/**
|
|
94
|
-
* Delete an account, restore one inside its purge window, and start a purge
|
|
95
|
-
* `DELETE {base}/admin/users/:userId` and `POST …/restore
|
|
94
|
+
* Delete an account, restore one inside its purge window, and start a purge:
|
|
95
|
+
* `DELETE {base}/admin/users/:userId` and `POST …/restore`. The
|
|
96
96
|
* one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
|
|
97
97
|
* gone from every capability that held them.
|
|
98
98
|
*/
|
|
99
99
|
export declare const AUTH_USERS_DELETE_SCOPE: ControlPlaneScope;
|
|
100
100
|
/**
|
|
101
|
-
* Export everything the kit holds about one account — the answer to an access request
|
|
102
|
-
* `GET {base}/admin/users/:userId/export
|
|
101
|
+
* Export everything the kit holds about one account — the answer to an access request:
|
|
102
|
+
* `GET {base}/admin/users/:userId/export`. A disclosure, and a far larger one than reading the user: it carries every capability's rows about
|
|
103
103
|
* them, so it is granted on its own and audited as one.
|
|
104
104
|
*/
|
|
105
105
|
export declare const AUTH_USERS_EXPORT_SCOPE: ControlPlaneScope;
|
|
106
|
+
/**
|
|
107
|
+
* Read the verification ledger: every sign-in link and code issued over a window, whether it was used,
|
|
108
|
+
* expired or is still waiting, and the mail that carried it. A read, and apart from `auth:users:read` because the question is the fleet's deliverability rather than
|
|
109
|
+
* who one person is — the rows name accounts by id and never by address.
|
|
110
|
+
*/
|
|
111
|
+
export declare const AUTH_VERIFICATIONS_READ_SCOPE: ControlPlaneScope;
|
|
106
112
|
/**
|
|
107
113
|
* Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
|
|
108
114
|
* and the list a manifest or a doc quotes rather than re-typing.
|
|
109
115
|
*
|
|
110
|
-
*
|
|
111
|
-
* landed in #621, delete, restore and export in #622. Declaring the vocabulary here, once, is what let those
|
|
112
|
-
* issues build on one name each rather than each choosing its own.
|
|
116
|
+
* Declaring the vocabulary here, once, gives every route that requires one of these the same name.
|
|
113
117
|
*/
|
|
114
118
|
export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
|
|
115
119
|
/**
|
|
@@ -124,5 +128,5 @@ export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
|
|
|
124
128
|
* The summaries say what the operation is *for*. A client renders these next to a button somebody is
|
|
125
129
|
* about to press on a real person's account.
|
|
126
130
|
*/
|
|
127
|
-
export declare function authAdminRoutes(basePath: string):
|
|
131
|
+
export declare function authAdminRoutes(basePath: string): AdminRouteDeclaration[];
|
|
128
132
|
//# sourceMappingURL=guards.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAUjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAqGzE"}
|
package/dist/http/guards.js
CHANGED
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
* every legitimate management call, permanently, and **no credential could fix it** — there is no user
|
|
27
27
|
* to sign in as. `controlPlaneIsolation.workers.test.ts` pins both directions of that separation.
|
|
28
28
|
*
|
|
29
|
-
* ##
|
|
29
|
+
* ## Nine scopes, because these are nine different blast radii
|
|
30
30
|
*
|
|
31
31
|
* The temptation is one `auth:admin` flag, and on this capability it is the most dangerous version of
|
|
32
32
|
* that mistake. **Reading a user is a privacy operation; revoking their sessions is an availability
|
|
@@ -84,31 +84,35 @@ const AUTH_USERS_LOGOUT_SCOPE = "auth:users:logout";
|
|
|
84
84
|
*/
|
|
85
85
|
const AUTH_DEVICES_REVOKE_SCOPE = "auth:devices:revoke";
|
|
86
86
|
/**
|
|
87
|
-
* Suspend an account and reinstate it
|
|
87
|
+
* Suspend an account and reinstate it: `POST {base}/admin/users/:userId/suspend` and `/reinstate`. Ending somebody's access is an availability
|
|
88
88
|
* operation on one person, and reversible — which is what separates it from deleting them, and why it is
|
|
89
89
|
* granted apart from both reading them and erasing them.
|
|
90
90
|
*/
|
|
91
91
|
const AUTH_USERS_SUSPEND_SCOPE = "auth:users:suspend";
|
|
92
92
|
/**
|
|
93
|
-
* Delete an account, restore one inside its purge window, and start a purge
|
|
94
|
-
* `DELETE {base}/admin/users/:userId` and `POST …/restore
|
|
93
|
+
* Delete an account, restore one inside its purge window, and start a purge:
|
|
94
|
+
* `DELETE {base}/admin/users/:userId` and `POST …/restore`. The
|
|
95
95
|
* one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
|
|
96
96
|
* gone from every capability that held them.
|
|
97
97
|
*/
|
|
98
98
|
const AUTH_USERS_DELETE_SCOPE = "auth:users:delete";
|
|
99
99
|
/**
|
|
100
|
-
* Export everything the kit holds about one account — the answer to an access request
|
|
101
|
-
* `GET {base}/admin/users/:userId/export
|
|
100
|
+
* Export everything the kit holds about one account — the answer to an access request:
|
|
101
|
+
* `GET {base}/admin/users/:userId/export`. A disclosure, and a far larger one than reading the user: it carries every capability's rows about
|
|
102
102
|
* them, so it is granted on its own and audited as one.
|
|
103
103
|
*/
|
|
104
104
|
const AUTH_USERS_EXPORT_SCOPE = "auth:users:export";
|
|
105
105
|
/**
|
|
106
|
+
* Read the verification ledger: every sign-in link and code issued over a window, whether it was used,
|
|
107
|
+
* expired or is still waiting, and the mail that carried it. A read, and apart from `auth:users:read` because the question is the fleet's deliverability rather than
|
|
108
|
+
* who one person is — the rows name accounts by id and never by address.
|
|
109
|
+
*/
|
|
110
|
+
const AUTH_VERIFICATIONS_READ_SCOPE = "auth:verifications:read";
|
|
111
|
+
/**
|
|
106
112
|
* Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
|
|
107
113
|
* and the list a manifest or a doc quotes rather than re-typing.
|
|
108
114
|
*
|
|
109
|
-
*
|
|
110
|
-
* landed in #621, delete, restore and export in #622. Declaring the vocabulary here, once, is what let those
|
|
111
|
-
* issues build on one name each rather than each choosing its own.
|
|
115
|
+
* Declaring the vocabulary here, once, gives every route that requires one of these the same name.
|
|
112
116
|
*/
|
|
113
117
|
const AUTH_CONTROL_PLANE_SCOPES = [
|
|
114
118
|
AUTH_USERS_READ_SCOPE,
|
|
@@ -118,7 +122,8 @@ const AUTH_CONTROL_PLANE_SCOPES = [
|
|
|
118
122
|
AUTH_DEVICES_REVOKE_SCOPE,
|
|
119
123
|
AUTH_USERS_SUSPEND_SCOPE,
|
|
120
124
|
AUTH_USERS_DELETE_SCOPE,
|
|
121
|
-
AUTH_USERS_EXPORT_SCOPE
|
|
125
|
+
AUTH_USERS_EXPORT_SCOPE,
|
|
126
|
+
AUTH_VERIFICATIONS_READ_SCOPE
|
|
122
127
|
];
|
|
123
128
|
/**
|
|
124
129
|
* Auth's management surface, as `GET /control-plane/manifest` reports it.
|
|
@@ -136,71 +141,101 @@ function authAdminRoutes(basePath) {
|
|
|
136
141
|
return [
|
|
137
142
|
{
|
|
138
143
|
method: "GET",
|
|
144
|
+
operation: "users.list",
|
|
139
145
|
path: `${basePath}/admin/users`,
|
|
140
146
|
scope: AUTH_USERS_READ_SCOPE,
|
|
147
|
+
kind: "reads",
|
|
141
148
|
summary: "Find a user. Lists everyone newest first, or searches email and display name."
|
|
142
149
|
},
|
|
143
150
|
{
|
|
144
151
|
method: "GET",
|
|
152
|
+
operation: "users.read",
|
|
145
153
|
path: `${basePath}/admin/users/:userId`,
|
|
146
154
|
scope: AUTH_USERS_READ_SCOPE,
|
|
155
|
+
kind: "reads",
|
|
147
156
|
summary: "One user, with where they are signed in and what they sign in with."
|
|
148
157
|
},
|
|
149
158
|
{
|
|
150
159
|
method: "GET",
|
|
160
|
+
operation: "devices.list",
|
|
151
161
|
path: `${basePath}/admin/devices`,
|
|
152
162
|
scope: AUTH_DEVICES_READ_SCOPE,
|
|
163
|
+
kind: "reads",
|
|
153
164
|
summary: "The device registry across users, most-recently-seen first."
|
|
154
165
|
},
|
|
155
166
|
{
|
|
156
167
|
method: "POST",
|
|
168
|
+
operation: "sessions.revoke",
|
|
157
169
|
path: `${basePath}/admin/sessions/revoke`,
|
|
158
170
|
scope: AUTH_SESSIONS_REVOKE_SCOPE,
|
|
171
|
+
kind: "credentials",
|
|
159
172
|
summary: "Kill one session. The rest of that person's sign-ins keep working."
|
|
160
173
|
},
|
|
161
174
|
{
|
|
162
175
|
method: "POST",
|
|
176
|
+
operation: "users.sessions.revoke",
|
|
163
177
|
path: `${basePath}/admin/users/:userId/sessions/revoke`,
|
|
164
178
|
scope: AUTH_USERS_LOGOUT_SCOPE,
|
|
179
|
+
kind: "credentials",
|
|
165
180
|
summary: "Sign a user out everywhere, on every device, immediately."
|
|
166
181
|
},
|
|
167
182
|
{
|
|
168
183
|
method: "POST",
|
|
184
|
+
operation: "users.devices.revoke",
|
|
169
185
|
path: `${basePath}/admin/users/:userId/devices/revoke`,
|
|
170
186
|
scope: AUTH_DEVICES_REVOKE_SCOPE,
|
|
187
|
+
kind: "credentials",
|
|
171
188
|
summary: "Sign one device out and forget it — for a phone reported lost."
|
|
172
189
|
},
|
|
173
190
|
{
|
|
174
191
|
method: "POST",
|
|
192
|
+
operation: "users.suspend",
|
|
175
193
|
path: `${basePath}/admin/users/:userId/suspend`,
|
|
176
194
|
scope: AUTH_USERS_SUSPEND_SCOPE,
|
|
195
|
+
kind: "writes",
|
|
177
196
|
summary: "Suspend a user, with a reason. Their sessions end and every sign-in is refused."
|
|
178
197
|
},
|
|
179
198
|
{
|
|
180
199
|
method: "POST",
|
|
200
|
+
operation: "users.reinstate",
|
|
181
201
|
path: `${basePath}/admin/users/:userId/reinstate`,
|
|
182
202
|
scope: AUTH_USERS_SUSPEND_SCOPE,
|
|
203
|
+
kind: "writes",
|
|
183
204
|
summary: "Lift a suspension, with a reason. They sign in again; no session comes back."
|
|
184
205
|
},
|
|
185
206
|
{
|
|
186
207
|
method: "DELETE",
|
|
208
|
+
operation: "users.delete",
|
|
187
209
|
path: `${basePath}/admin/users/:userId`,
|
|
188
210
|
scope: AUTH_USERS_DELETE_SCOPE,
|
|
211
|
+
kind: "deletes",
|
|
189
212
|
summary: "Delete a user, with a reason. Soft by default: restorable until the purge window closes. Hard, when named: erased now."
|
|
190
213
|
},
|
|
191
214
|
{
|
|
192
215
|
method: "POST",
|
|
216
|
+
operation: "users.restore",
|
|
193
217
|
path: `${basePath}/admin/users/:userId/restore`,
|
|
194
218
|
scope: AUTH_USERS_DELETE_SCOPE,
|
|
219
|
+
kind: "deletes",
|
|
195
220
|
summary: "Restore a deleted user inside the purge window, with a reason. They sign in again."
|
|
196
221
|
},
|
|
197
222
|
{
|
|
198
223
|
method: "GET",
|
|
224
|
+
operation: "verifications.list",
|
|
225
|
+
path: `${basePath}/admin/verifications`,
|
|
226
|
+
scope: AUTH_VERIFICATIONS_READ_SCOPE,
|
|
227
|
+
kind: "reads",
|
|
228
|
+
summary: "Every sign-in link and code sent over a window: used, expired or still waiting, and the mail that carried it."
|
|
229
|
+
},
|
|
230
|
+
{
|
|
231
|
+
method: "GET",
|
|
232
|
+
operation: "users.export",
|
|
199
233
|
path: `${basePath}/admin/users/:userId/export`,
|
|
200
234
|
scope: AUTH_USERS_EXPORT_SCOPE,
|
|
235
|
+
kind: "reads",
|
|
201
236
|
summary: "Everything the kit holds about one user, from every capability — the answer to an access request."
|
|
202
237
|
}
|
|
203
238
|
];
|
|
204
239
|
}
|
|
205
240
|
//#endregion
|
|
206
|
-
export { AUTH_CONTROL_PLANE_SCOPES, AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, authAdminRoutes };
|
|
241
|
+
export { AUTH_CONTROL_PLANE_SCOPES, AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, AUTH_VERIFICATIONS_READ_SCOPE, authAdminRoutes };
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
4
|
+
import type { Context } from "hono";
|
|
5
|
+
import type { AuthWiring } from "../capability";
|
|
6
|
+
import type { AuthInstance } from "../instance/auth";
|
|
7
|
+
import type { HandoffExchangeBody, SocialSignInStartQuery } from "./schemas";
|
|
8
|
+
/**
|
|
9
|
+
* The redirect half of a native sign-in, and the trade that ends it.
|
|
10
|
+
*
|
|
11
|
+
* A native app starts a social sign-in with its own deep link as `callbackURL` (a scheme in `trustedOrigins`,
|
|
12
|
+
* such as `myapp://auth/callback`). Better Auth checks that URL when the sign-in starts and, at the provider's
|
|
13
|
+
* callback, answers with a redirect to it carrying the session as a cookie. A cookie set on a redirect to an app
|
|
14
|
+
* scheme lands in the system browser, which the app never reads. {@link handOffToApp} replaces that answer: the
|
|
15
|
+
* session cookies are dropped and the deep link carries a one-time code instead (`../token/handoff.ts`). The app
|
|
16
|
+
* posts the code to `POST {base}/handoff`, {@link exchangeHandoff}, and gets the raw session token back.
|
|
17
|
+
*
|
|
18
|
+
* The code is bound to the app that asked for it. The app puts the S256 challenge of a verifier only it holds on
|
|
19
|
+
* its `callbackURL` as `handoff_challenge`, Better Auth keeps that URL with the sign-in's state, and the challenge
|
|
20
|
+
* comes back here on the redirect. It is moved off the link and stored with the code, and the trade must present
|
|
21
|
+
* the verifier. A deep link with no challenge gets no code at all.
|
|
22
|
+
*
|
|
23
|
+
* Which redirects are handed off: any whose link carries `handoff_challenge`, whatever its scheme, and any to a
|
|
24
|
+
* non-http(s) scheme. So an app's https universal link (iOS) or app link (Android), which the operating system
|
|
25
|
+
* routes only to the app that proves it owns the domain, gets a code when the app asks for one with a challenge.
|
|
26
|
+
* An http(s) callback with no challenge is a web page, and a web page gets its cookie.
|
|
27
|
+
*
|
|
28
|
+
* A magic link is handed off only to an https link. Whoever asks for the link chooses the challenge, and the
|
|
29
|
+
* person who opens it is somebody else, so the code must reach only the app that owns the link's domain. Any app
|
|
30
|
+
* can claim a custom scheme; a magic link to one is refused, and a native app without a universal link signs in
|
|
31
|
+
* by email with a one-time code instead.
|
|
32
|
+
*
|
|
33
|
+
* A native app starts a redirect sign-in with {@link startNativeSignIn}, a GET the system browser's sign-in sheet
|
|
34
|
+
* opens, rather than by posting `/sign-in/social` itself. Better Auth binds the sign-in to a signed `state`
|
|
35
|
+
* cookie and checks it at the provider's callback; set on the app's own request, that cookie would never reach
|
|
36
|
+
* the sheet that completes the callback.
|
|
37
|
+
*/
|
|
38
|
+
/** The deep-link query parameter the one-time code travels in. */
|
|
39
|
+
export declare const HANDOFF_CODE_PARAM = "code";
|
|
40
|
+
/** The `callbackURL` query parameter the app's S256 challenge travels in. */
|
|
41
|
+
export declare const HANDOFF_CHALLENGE_PARAM = "handoff_challenge";
|
|
42
|
+
/** The `error` a deep link gets back when it carried no challenge to bind a code to. */
|
|
43
|
+
export declare const HANDOFF_UNBOUND_ERROR = "handoff_challenge_required";
|
|
44
|
+
/** The `error` a magic link to a custom scheme gets back: only an https universal link or app link is handed one. */
|
|
45
|
+
export declare const HANDOFF_SCHEME_REFUSED_ERROR = "handoff_scheme_refused";
|
|
46
|
+
type Ctx = Context<PithyHonoEnv>;
|
|
47
|
+
/**
|
|
48
|
+
* Rewrite a sign-in that ends on an app link into a handoff, or answer null and leave the response as Better Auth
|
|
49
|
+
* wrote it: any answer that is not a redirect to an app link, and a redirect that sets no session (a refused
|
|
50
|
+
* sign-in returning its error to the app).
|
|
51
|
+
*
|
|
52
|
+
* An app link outside `trustedOrigins` is refused rather than followed. Better Auth checked the callback when the
|
|
53
|
+
* sign-in started, so reaching that branch means something else wrote the redirect, and a session must never be
|
|
54
|
+
* handed to a scheme this Worker does not trust.
|
|
55
|
+
*/
|
|
56
|
+
export declare function handOffToApp(c: Ctx, wiring: AuthWiring, instance: AuthInstance, response: Response): Promise<Response | null>;
|
|
57
|
+
/**
|
|
58
|
+
* Start a native redirect sign-in inside the system browser's sign-in sheet: run the social sign-in here and
|
|
59
|
+
* answer a redirect to the provider that carries Better Auth's `Set-Cookie`, so the signed `state` cookie lands in
|
|
60
|
+
* the jar of the browser that will come back through the provider's callback.
|
|
61
|
+
*
|
|
62
|
+
* Only for the handoff: the callback must be a link `trustedOrigins` admits, carrying a well-formed
|
|
63
|
+
* `handoff_challenge`, and a navigation another page started (`Sec-Fetch-Site` other than `none`) is refused. A web page starts its sign-in with the JSON `POST /sign-in/social`, as it always has.
|
|
64
|
+
* The sign-in runs on a request of its own with the sheet's cookies, origin and fetch metadata left behind:
|
|
65
|
+
* nothing the sheet already holds takes part in it.
|
|
66
|
+
*/
|
|
67
|
+
export declare function startNativeSignIn(c: Ctx, wiring: AuthWiring, query: SocialSignInStartQuery): Promise<Response>;
|
|
68
|
+
/**
|
|
69
|
+
* Trade a one-time code and its verifier for the session the code stands for. The code is spent by the attempt
|
|
70
|
+
* whatever the answer, so a wrong verifier gets one guess.
|
|
71
|
+
* Device headers sent with the trade register the device and bind it to the session, as they would on any other
|
|
72
|
+
* native sign-in; the browser that completed the redirect had none to send.
|
|
73
|
+
*/
|
|
74
|
+
export declare function exchangeHandoff(c: Ctx, wiring: AuthWiring, body: HandoffExchangeBody): Promise<Response>;
|
|
75
|
+
export {};
|
|
76
|
+
//# sourceMappingURL=handoff.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/http/handoff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAQ7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE,qHAAqH;AACrH,eAAO,MAAM,4BAA4B,2BAA2B,CAAC;AAKrE,KAAK,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AA8CjC;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,CAAC,EAAE,GAAG,EACN,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA+E1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgFpH;AAYD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6B9G"}
|