@pithy-sh/auth 0.9.0 → 0.11.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 +8 -2
- package/dist/admin/users.js +1 -1
- package/dist/audit/actions.d.ts +40 -0
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +41 -1
- package/dist/audit/emit.d.ts +2 -0
- package/dist/audit/emit.d.ts.map +1 -1
- package/dist/audit/emit.js +2 -2
- package/dist/capability.d.ts +45 -1
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +40 -5
- package/dist/client/lifecycle.d.ts +19 -0
- package/dist/client/lifecycle.d.ts.map +1 -0
- package/dist/client/lifecycle.js +25 -0
- package/dist/client/projection.d.ts +4 -0
- package/dist/client/projection.d.ts.map +1 -1
- package/dist/data/betterAuth.d.ts +4 -0
- package/dist/data/betterAuth.d.ts.map +1 -1
- package/dist/data/betterAuth.js +6 -2
- package/dist/data/kitFields.d.ts +20 -25
- package/dist/data/kitFields.d.ts.map +1 -1
- package/dist/data/kitFields.js +28 -32
- package/dist/data/tables.d.ts +29 -2
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -3
- package/dist/data/userLifecycle.d.ts +62 -0
- package/dist/data/userLifecycle.d.ts.map +1 -0
- package/dist/data/userLifecycle.js +51 -0
- package/dist/http/adminRoutes.d.ts.map +1 -1
- package/dist/http/adminRoutes.js +270 -5
- package/dist/http/guards.d.ts +24 -1
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +59 -3
- package/dist/http/lifecycleGate.d.ts +18 -0
- package/dist/http/lifecycleGate.d.ts.map +1 -0
- package/dist/http/lifecycleGate.js +75 -0
- package/dist/http/middleware.d.ts +30 -1
- package/dist/http/middleware.d.ts.map +1 -1
- package/dist/http/middleware.js +89 -7
- package/dist/http/providerRefusal.d.ts.map +1 -1
- package/dist/http/providerRefusal.js +8 -0
- package/dist/http/resolve.d.ts.map +1 -1
- package/dist/http/resolve.js +7 -4
- package/dist/http/responses.d.ts +180 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +142 -1
- package/dist/http/routes.d.ts +1 -0
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +65 -4
- package/dist/http/schemas.d.ts +57 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +51 -1
- package/dist/http/views.d.ts +39 -2
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +105 -1
- package/dist/instance/auth.d.ts +55 -3
- package/dist/instance/auth.d.ts.map +1 -1
- package/dist/instance/auth.js +53 -2
- package/dist/instance/microsoftEmail.d.ts +70 -0
- package/dist/instance/microsoftEmail.d.ts.map +1 -0
- package/dist/instance/microsoftEmail.js +96 -0
- package/dist/instance/providerSignInGate.d.ts +7 -6
- package/dist/instance/providerSignInGate.d.ts.map +1 -1
- package/dist/instance/providerSignInGate.js +7 -6
- package/dist/instance/providers.d.ts +7 -5
- package/dist/instance/providers.d.ts.map +1 -1
- package/dist/instance/providers.js +5 -3
- package/dist/instance/secrets.d.ts +64 -3
- package/dist/instance/secrets.d.ts.map +1 -1
- package/dist/instance/secrets.js +44 -5
- package/dist/lifecycle/audited.d.ts +48 -0
- package/dist/lifecycle/audited.d.ts.map +1 -0
- package/dist/lifecycle/audited.js +65 -0
- package/dist/lifecycle/enforce.d.ts +75 -0
- package/dist/lifecycle/enforce.d.ts.map +1 -0
- package/dist/lifecycle/enforce.js +111 -0
- package/dist/lifecycle/hooks.d.ts +53 -0
- package/dist/lifecycle/hooks.d.ts.map +1 -0
- package/dist/lifecycle/hooks.js +2 -0
- package/dist/lifecycle/reason.d.ts +11 -0
- package/dist/lifecycle/reason.d.ts.map +1 -0
- package/dist/lifecycle/reason.js +13 -0
- package/dist/lifecycle/request.d.ts +18 -0
- package/dist/lifecycle/request.d.ts.map +1 -0
- package/dist/lifecycle/request.js +31 -0
- package/dist/lifecycle/state.d.ts +64 -0
- package/dist/lifecycle/state.d.ts.map +1 -0
- package/dist/lifecycle/state.js +90 -0
- package/dist/lifecycle/transitions.d.ts +272 -0
- package/dist/lifecycle/transitions.d.ts.map +1 -0
- package/dist/lifecycle/transitions.js +623 -0
- package/dist/migrations/0004_user_lifecycle.d.ts +28 -0
- package/dist/migrations/0004_user_lifecycle.d.ts.map +1 -0
- package/dist/migrations/0004_user_lifecycle.js +47 -0
- package/dist/migrations/0005_purge_once.d.ts +22 -0
- package/dist/migrations/0005_purge_once.d.ts.map +1 -0
- package/dist/migrations/0005_purge_once.js +35 -0
- package/dist/migrations/pluginTables.d.ts +8 -0
- package/dist/migrations/pluginTables.d.ts.map +1 -1
- package/dist/migrations/pluginTables.js +8 -1
- package/dist/migrations/set.d.ts +3 -1
- package/dist/migrations/set.d.ts.map +1 -1
- package/dist/migrations/set.js +6 -2
- package/dist/peer.d.ts +4 -0
- package/dist/peer.d.ts.map +1 -1
- package/dist/purge/contribution.d.ts +47 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +141 -0
- package/dist/purge/retryPolicy.d.ts +22 -0
- package/dist/purge/retryPolicy.d.ts.map +1 -0
- package/dist/purge/retryPolicy.js +26 -0
- package/dist/purge/run.d.ts +88 -0
- package/dist/purge/run.d.ts.map +1 -0
- package/dist/purge/run.js +102 -0
- package/dist/purge/specs.d.ts +71 -0
- package/dist/purge/specs.d.ts.map +1 -0
- package/dist/purge/specs.js +72 -0
- package/dist/purge/start.d.ts +42 -0
- package/dist/purge/start.d.ts.map +1 -0
- package/dist/purge/start.js +37 -0
- package/dist/purge/workflow.d.ts +58 -0
- package/dist/purge/workflow.d.ts.map +1 -0
- package/dist/purge/workflow.js +96 -0
- package/dist/test-utils/accountFootprint.d.ts +10 -0
- package/dist/test-utils/accountFootprint.d.ts.map +1 -0
- package/dist/test-utils/accountFootprint.js +44 -0
- package/dist/test-utils/liveApp.d.ts +21 -0
- package/dist/test-utils/liveApp.d.ts.map +1 -1
- package/dist/test-utils/liveApp.js +1 -0
- package/dist/test-utils/scopedBackend.d.ts +21 -0
- package/dist/test-utils/scopedBackend.d.ts.map +1 -1
- package/dist/test-utils/scopedBackend.js +7 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.d.ts.map +1 -1
- package/dist/version.generated.js +1 -1
- package/docs/account-lifecycle.md +217 -0
- package/docs/apple-signin.md +7 -1
- package/docs/facebook-oauth.md +7 -1
- package/docs/github-oauth.md +7 -1
- package/docs/google-oauth.md +7 -1
- package/docs/microsoft-oauth.md +177 -0
- package/package.json +5 -5
- package/pithy.manifest.json +17 -3
- package/src/audit/actions.ts +42 -0
- package/src/audit/emit.ts +4 -2
- package/src/capability.ts +170 -52
- package/src/client/lifecycle.ts +27 -0
- package/src/client/projection.ts +4 -0
- package/src/data/betterAuth.ts +21 -1
- package/src/data/kitFields.ts +27 -0
- package/src/data/tables.ts +4 -2
- package/src/data/userLifecycle.ts +83 -0
- package/src/http/adminRoutes.ts +398 -2
- package/src/http/guards.ts +61 -1
- package/src/http/lifecycleGate.ts +78 -0
- package/src/http/middleware.ts +104 -2
- package/src/http/providerRefusal.ts +10 -0
- package/src/http/resolve.ts +8 -3
- package/src/http/responses.ts +245 -0
- package/src/http/routes.ts +93 -4
- package/src/http/schemas.ts +110 -0
- package/src/http/views.ts +147 -2
- package/src/instance/auth.ts +74 -2
- package/src/instance/microsoftEmail.ts +111 -0
- package/src/instance/providerSignInGate.ts +7 -6
- package/src/instance/providers.ts +8 -4
- package/src/instance/secrets.ts +59 -5
- package/src/lifecycle/audited.ts +104 -0
- package/src/lifecycle/enforce.ts +139 -0
- package/src/lifecycle/hooks.ts +54 -0
- package/src/lifecycle/reason.ts +11 -0
- package/src/lifecycle/request.ts +39 -0
- package/src/lifecycle/state.ts +101 -0
- package/src/lifecycle/transitions.ts +872 -0
- package/src/migrations/0004_user_lifecycle.ts +68 -0
- package/src/migrations/0005_purge_once.ts +42 -0
- package/src/migrations/pluginTables.ts +19 -1
- package/src/migrations/set.ts +5 -1
- package/src/purge/contribution.ts +191 -0
- package/src/purge/retryPolicy.ts +26 -0
- package/src/purge/run.ts +185 -0
- package/src/purge/specs.ts +95 -0
- package/src/purge/start.ts +79 -0
- package/src/purge/workflow.ts +144 -0
- package/src/test-utils/accountFootprint.ts +95 -0
- package/src/test-utils/liveApp.ts +2 -1
- package/src/test-utils/scopedBackend.ts +2 -1
- package/src/version.generated.ts +1 -1
|
@@ -52,6 +52,11 @@ const SCOPED_SECRETS = {
|
|
|
52
52
|
clientId: "h",
|
|
53
53
|
clientSecret: "h"
|
|
54
54
|
},
|
|
55
|
+
"auth-microsoft-credentials": {
|
|
56
|
+
clientId: "m",
|
|
57
|
+
clientSecret: "m",
|
|
58
|
+
tenantId: "common"
|
|
59
|
+
},
|
|
55
60
|
"email-link-signing-key": "dev-link-signing-key"
|
|
56
61
|
};
|
|
57
62
|
/**
|
|
@@ -130,7 +135,8 @@ async function signInScoped(db, address = "player@test.com") {
|
|
|
130
135
|
google: true,
|
|
131
136
|
apple: true,
|
|
132
137
|
facebook: true,
|
|
133
|
-
github: true
|
|
138
|
+
github: true,
|
|
139
|
+
microsoft: true
|
|
134
140
|
},
|
|
135
141
|
emit: async () => {},
|
|
136
142
|
plugins: []
|
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
/** This package's npm name — the join key against a release feed. */
|
|
4
4
|
export declare const PACKAGE_NAME = "@pithy-sh/auth";
|
|
5
5
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
6
|
-
export declare const PACKAGE_VERSION = "0.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.11.0";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,eAAe,
|
|
1
|
+
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,eAAe,WAAW,CAAC"}
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
/** This package's npm name — the join key against a release feed. */
|
|
5
5
|
const PACKAGE_NAME = "@pithy-sh/auth";
|
|
6
6
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
7
|
-
const PACKAGE_VERSION = "0.
|
|
7
|
+
const PACKAGE_VERSION = "0.11.0";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# Account lifecycle
|
|
2
|
+
|
|
3
|
+
An account can be suspended or deleted. The kit holds the state, enforces it at every door, records every transition, and sends the mail. An operator suspends, reinstates, deletes, restores and exports an account through control-plane routes, below. A person deletes their own account from inside your app. A purge erases a deleted account's data from every capability that holds it, once its window closes.
|
|
4
|
+
|
|
5
|
+
## Two states
|
|
6
|
+
|
|
7
|
+
| State | Columns | What it means | Ends |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| Suspended | `suspended_at`, `suspended_until` | The account cannot sign in, refresh a token, or act on any route. | At `suspended_until`, by itself, or when an operator reinstates it. |
|
|
10
|
+
| Deleted | `deleted_at`, `purge_after` | The same, and its data is due for erasure once the purge window closes. Restorable until then. | When it is restored inside the window, or when the purge erases it. |
|
|
11
|
+
|
|
12
|
+
Both live on `pithy_auth_users`, so a session read already carries them. An account in good standing costs no extra read, and neither does refusing a deleted one. Refusing a suspended account costs one: the operator's reason is read from `pithy_auth_user_lifecycle`, on every refused request. A deleted account outranks a suspension it was already under. A suspension past its `suspended_until` is not a suspension, and nothing has to be written to end it.
|
|
13
|
+
|
|
14
|
+
No client can write its own state. The four columns are `input: false`, and only the kit's transitions set them.
|
|
15
|
+
|
|
16
|
+
## Enforcement
|
|
17
|
+
|
|
18
|
+
A refused request gets one of two errors, both 403:
|
|
19
|
+
|
|
20
|
+
- `auth/account_suspended` — the operator's reason is the `message`, and `params.suspendedUntil` names the end, as ISO-8601, when there is one.
|
|
21
|
+
- `auth/account_deleted` — `params.purgeAfter` names the last day it can be restored.
|
|
22
|
+
|
|
23
|
+
Not 401: signing in again cannot help. `clientError` strips `action` and `detail` from both, so a caller learns the state and the reason and nothing else. `@pithy-sh/i18n` carries each in Spanish, keyed by the code. The English is the `message`.
|
|
24
|
+
|
|
25
|
+
Where an account is refused:
|
|
26
|
+
|
|
27
|
+
- **Every request.** The session middleware gives a refused account no `AuthContext`, so every `requireAuth()` in the kit refuses it, whichever capability wrote the guard. This capability's own `requireAuth()` answers with the code. Another capability's copy answers 401, and the client's next refresh gets the code.
|
|
28
|
+
- **Every sign-in and every token refresh.** Magic link, OTP, each social provider and `/token/rotate` all create their session in one place, and that place refuses. A refused rotation spends nothing: the presented credential still works once the account is reinstated.
|
|
29
|
+
- **Better Auth's own endpoints.** `/token`, `/get-session` and the rest of what acts as the session's holder refuse too. Signing out always works, and a stale credential on a shared device never stops somebody else signing in.
|
|
30
|
+
|
|
31
|
+
A check that cannot be made refuses. If the read behind it fails, the request gets a `core/internal` 500 at every door above, never a session.
|
|
32
|
+
|
|
33
|
+
A magic link for a refused account returns to the screen it named, with the code as `?error=`. So does a social sign-in, to its `errorCallbackURL`. The callback and sign-in screens send the reader on to the screen for that state. So does the OTP screen, when a right code meets a refused account.
|
|
34
|
+
|
|
35
|
+
## The record
|
|
36
|
+
|
|
37
|
+
`pithy_auth_user_lifecycle` holds every transition: the action, the actor, the reason, the time. The columns say what is true now; the table says what happened and who did it. The two are written in one transaction, so neither is ever there without the other. It has no foreign key to the user, because a purge erases the user row and this record must outlive it. It is the one `pithy_auth_*` row the purge leaves behind.
|
|
38
|
+
|
|
39
|
+
A transition that finds the account already where it was asked to put it does nothing: no row, no event, no mail, no hook. The control-plane routes still record the call on the trail, as below. A suspension past its end counts as no suspension, so reinstating it is nothing too. A deleted account cannot be suspended or reinstated; restore it first, and its suspension is still there to lift.
|
|
40
|
+
|
|
41
|
+
Suspending an account that is already suspended is the one exception. It restates the suspension: the new reason and end replace the old, a row records them, and the mail and the audit event go out. The start stays, and no hook fires, because the account was suspended and still is.
|
|
42
|
+
|
|
43
|
+
Each transition also writes an audit event: `auth/admin_user_suspended`, `auth/admin_user_reinstated`, `auth/admin_user_soft_deleted`, `auth/admin_user_hard_deleted`, `auth/admin_user_restored`, `auth/admin_user_purged`, and `auth/user_self_deleted` when the account's holder deletes it. An export writes `auth/admin_user_exported`.
|
|
44
|
+
|
|
45
|
+
## Scopes
|
|
46
|
+
|
|
47
|
+
Reading a user, ending their access, and erasing them are three grants, beside `auth:users:read`:
|
|
48
|
+
|
|
49
|
+
- `auth:users:suspend` — suspend and reinstate.
|
|
50
|
+
- `auth:users:delete` — delete, restore, and start a purge.
|
|
51
|
+
- `auth:users:export` — everything the kit holds about one account, for an access request.
|
|
52
|
+
|
|
53
|
+
None of them is implied by another. See [CONTROL-PLANE.md](../../../docs/CONTROL-PLANE.md) for how a connection is granted one.
|
|
54
|
+
|
|
55
|
+
## Suspend and reinstate
|
|
56
|
+
|
|
57
|
+
Two routes, each gated by `auth:users:suspend`. A connection holding only `auth:users:read` is refused 403, and the scope is checked before the body is read.
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
POST /auth/admin/users/:userId/suspend { reason, until?, notify? }
|
|
61
|
+
POST /auth/admin/users/:userId/reinstate { reason, notify? }
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The paths are under auth's `basePath` (`/auth` by default), which the manifest reports — not under `/control-plane`, which holds only the seam's own routes. `reason` is required on both: one sentence, at most 500 characters, written for the person, because a suspension's reason is what every refused sign-in shows them. A request without one is `validation/invalid_input`.
|
|
65
|
+
|
|
66
|
+
**Suspend** stamps the columns, writes the row, and then revokes every session the account holds. A refresh token is a session token, so it goes with them. Revoked after the columns, never before: a session alive in between meets `auth/account_suspended`. The person's held credential stops working, a refresh is refused, and signing in again answers `auth/account_suspended` with the reason. `until` is an ISO-8601 time in the future; one in the past is refused. The suspension ends by itself when it passes, with nothing written. Suspending a suspended account restates it, and the response says `outcome: "updated"`. The response carries the suspension in force, `sessionsRevoked`, and `mailed`.
|
|
67
|
+
|
|
68
|
+
**Reinstate** lifts the suspension. It restores no session: the person signs in again. An account with no suspension in force answers 200 with `outcome: "unchanged"`, and nothing is written.
|
|
69
|
+
|
|
70
|
+
Neither touches a deleted account. Both answer `core/conflict`, naming the restore route, because a deleted account is restored, not reinstated. An unknown `:userId` is a 404.
|
|
71
|
+
|
|
72
|
+
`notify` is true when absent. It sends the account-suspended mail, or the account-reinstated mail, through `@pithy-sh/email`. `notify: false` sends none. The config can turn a mail off for every call; `notify` turns it off for one.
|
|
73
|
+
|
|
74
|
+
Every call is audited, as `auth/admin_user_suspended` or `auth/admin_user_reinstated`, with the operator, the connection, the reason and the user id. A refusal is recorded as `denied` with its code — a body the validator turns away included, with whatever reason it carried — and a reinstatement that changed nothing as a success with `changed: false`. The sessions a suspension ends are recorded as `auth/admin_user_sessions_revoked`, `cause: "suspended"`.
|
|
75
|
+
|
|
76
|
+
## Delete, restore and export
|
|
77
|
+
|
|
78
|
+
Three routes. Deleting and restoring are gated by `auth:users:delete`, exporting by `auth:users:export`. Neither grants the other, and `auth:users:read` grants neither. The scope is checked before the body is read.
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
DELETE /auth/admin/users/:userId { mode?, reason, notify? }
|
|
82
|
+
POST /auth/admin/users/:userId/restore { reason }
|
|
83
|
+
GET /auth/admin/users/:userId/export?reason=…
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`reason` is required on all three, on the same terms as a suspension's. A request without one is `validation/invalid_input`.
|
|
87
|
+
|
|
88
|
+
**Two modes, and soft is the default.** `mode: "soft"`, or no mode at all, stamps `deleted_at` and `purge_after` — now plus `retention.purgeAfterDays`, 30 unless you set it — and revokes every session the account holds. Signing in again answers `auth/account_deleted`. The deletion-scheduled mail goes out with the purge date and, when you configure one, the restore path. `onUserDeleted` fires. The account can be restored until `purge_after`. `mode: "hard"` closes the window now: `purge_after` is the moment of the deletion, nothing can restore it, and the purge starts in the same call. You name it on purpose. A typo — `"Hard"`, `"hrad"` — is a 400, never either mode. A hard deletion of an account already deleted softly brings its purge forward to now.
|
|
89
|
+
|
|
90
|
+
The response says what happened: `outcome` is `deleted`, `brought_forward`, or `unchanged` for an account already deleted. `purge` is `scheduled` for a soft deletion, `started` when this call started the purge, and `pending` when the account is due and this Worker binds no purge Workflow to start. `notify: false` silences the mail this call sends: the deletion-scheduled notice for soft, the deletion-complete notice for hard.
|
|
91
|
+
|
|
92
|
+
**Restore** clears both columns inside the window and records it. The person signs in again; no session comes back. A suspension the account was under before the deletion is still there, and the response says `state: "suspended"`. Once `purge_after` has passed the purge is due, so a restore is a 409 naming the date. The window is checked against the database's clock as the restore's write runs, the same clock the purge checks it against, so a restore and a purge that race always agree on which one won. A window that closes while a restore is in flight, or that a hard deletion brings forward, is the same 409. After the purge there is no account: a 404, whose action says the data is gone.
|
|
93
|
+
|
|
94
|
+
**Export** answers an access request. It returns one JSON document, validated by `AdminUserExportResponse` from `@pithy-sh/auth/src/http/responses`: the subject, when it was read, and one entry per composed capability that declares a purge contribution, in the order the purge erases them. An entry is `exported` with that capability's data, `not_exported` when it erases rows it does not say how to export, or `unavailable` when its rows would not read. Auth's own part is `AuthUserExport`: the account, its sessions, linked providers, devices, history and its rows in the user-keyed tables its Better Auth plugins created, and no credential — no session token, no provider token, no push token, no two-factor secret or backup code, no key. It is audited as a disclosure, `auth/admin_user_exported`, with the operator, the reason, and which parts answered, never the data. An unknown or purged account is a 404.
|
|
95
|
+
|
|
96
|
+
Every call is audited, as for suspend and reinstate: a deletion under `auth/admin_user_soft_deleted` or `auth/admin_user_hard_deleted`, a restore under `auth/admin_user_restored`, with the operator, the connection, the reason and the user id. A refusal is `denied` with its code, and a call that changed nothing is a success with `changed: false`.
|
|
97
|
+
|
|
98
|
+
## Deleting your own account
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
DELETE /auth/account { confirm: true }
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The signed-in person deletes their own account. **This is the route the App Store and Google Play require**: an app that lets people create an account must let them delete it from inside the app. Put a button behind it in your settings screen, and send `confirm: true` once the person has confirmed. Without the confirmation it is a 400 and nothing moves.
|
|
105
|
+
|
|
106
|
+
It is always soft, on the configured window, and the subject is always the session's own: no field names an account, and a key that tries is dropped. Every session ends, this one included. It is audited as `auth/user_self_deleted`, with the person as the actor. A suspended account can still delete itself — a suspension is no reason to keep somebody who wants to leave. A deleted one is refused with `auth/account_deleted`.
|
|
107
|
+
|
|
108
|
+
**Signing in to leave.** A suspension ends every session and refuses every sign-in, so a suspended person holds no credential to call this route with. A sign-in that sends `x-pithy-intent: delete-account` is the way back in: the person signs in as usual, by code, link or provider, and the suspended account gets a session anyway. That session opens nothing else. Every other route, a token and a refresh included, still answers `auth/account_suspended`, and `DELETE /auth/account` is the one that admits it. When a sign-in answers `auth/account_suspended`, offer the person a delete button that signs in again with the header and then calls this route. A deleted account is refused with or without the header. The header only works on a sign-in request your app sends itself, such as the OTP or an ID-token sign-in. A browser redirect, such as a magic link or a web social callback, cannot carry it. CSRF-guarded in cookie mode, like every mutating route.
|
|
109
|
+
|
|
110
|
+
**The restore path.** A person who changes their mind inside the window cannot sign in to undo it, so the deletion-scheduled mail tells them how: its restore button links to `retention.restoreUrl` when you set one — an http(s) page of yours — and the mail always says to reply before the purge date. An operator restores the account from the management surface.
|
|
111
|
+
|
|
112
|
+
## The purge
|
|
113
|
+
|
|
114
|
+
A purge erases one deleted account from every capability that holds rows about it. It runs as a Workflow, **one step per composed purge contribution**, named for its capability, so a capability that fails retries alone and the steps that finished are not run again. Each step records that it ran in `pithy_auth_user_lifecycle`, with the contribution's summary. The order:
|
|
115
|
+
|
|
116
|
+
1. Is the account due — deleted, with its window closed? A restored account, one inside its window, and one already erased end the run here, having erased nothing. Re-running a purge for the same subject exits without error.
|
|
117
|
+
2. Every composed contribution but auth's, in composition order, your `app` last.
|
|
118
|
+
3. The deletion-complete mail, **before the address is erased**: auth's rows, which hold it, are still there.
|
|
119
|
+
4. Auth's own: the user row, its sessions, linked providers, devices, refresh-token ledger and pending sign-in codes, and its rows in every table a composed Better Auth plugin created with a `userId` column — a two-factor secret and its backup codes, a passkey, an API key. Its history stays — the one `pithy_auth_*` row left. `organization()`'s tables are not erased yet; a membership is the organization's as much as the person's.
|
|
120
|
+
5. The `purged` record, `auth/admin_user_purged`, and `onUserPurged`, once — even when two purges of one account overlap.
|
|
121
|
+
|
|
122
|
+
A daily cron at 02:00 UTC starts the purge for every account past its `purge_after`, and for none before it. A hard deletion starts its own. Either way the instance is named for the deletion and the UTC day, so a hard deletion repeated, or one the daily pass also finds due, is one purge, and a purge that failed is started again by the next day's pass. A hard deletion's `notify: false` is saved with the deletion, so it holds when the daily pass is the one that starts its purge.
|
|
123
|
+
|
|
124
|
+
The `scheduled` handler starts only the jobs whose `schedule` is the cron that fired, so the daily pass runs once a day even in a Worker whose other jobs run hourly.
|
|
125
|
+
|
|
126
|
+
**The Workflows are yours to export.** A purge runs every composed capability's contribution, your own among them, and only the Worker that composes auth has them. So the two classes are five lines each in that Worker's entry, beside `createEntrypoint`, and their bodies are the kit's:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
// apps/api/src/index.ts
|
|
130
|
+
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
131
|
+
import { NonRetryableError } from "cloudflare:workflows";
|
|
132
|
+
import { runAuthPurge, runAuthPurgeDue } from "@pithy-sh/auth/src/purge/workflow";
|
|
133
|
+
|
|
134
|
+
export class AuthPurgeWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
|
|
135
|
+
override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
|
|
136
|
+
return runAuthPurge(this.env, event, step, NonRetryableError);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export class AuthPurgeDueWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
|
|
141
|
+
override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
|
|
142
|
+
return runAuthPurgeDue(this.env, event, step, NonRetryableError);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
```jsonc
|
|
148
|
+
// apps/api/wrangler.jsonc, in each environment's stanza
|
|
149
|
+
"workflows": [
|
|
150
|
+
{ "binding": "AUTH_PURGE", "name": "acme-prod-auth-purge", "class_name": "AuthPurgeWorkflow" },
|
|
151
|
+
{ "binding": "AUTH_PURGE_DUE", "name": "acme-prod-auth-purge-due", "class_name": "AuthPurgeDueWorkflow" }
|
|
152
|
+
],
|
|
153
|
+
"triggers": { "crons": ["0 2 * * *"] }
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`pithy worker sync` leaves these entries and the cron where you wrote them, and `pithy deploy` does not count them against your app's own Workflows. Until they are bound, deletions still shut the account, a hard deletion reports its purge as `pending`, and nothing is erased. `c.var.workflows.trigger("auth/purge-due", {})` runs the daily pass on demand.
|
|
157
|
+
|
|
158
|
+
The purge audits from the Workflow through the composed audit capability, which provides a recorder for code with no request. With no audit capability composed, nothing is recorded, as for every other event.
|
|
159
|
+
|
|
160
|
+
## Config
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
auth({
|
|
164
|
+
baseURL: "https://api.example.com",
|
|
165
|
+
// How long a deleted account waits before the purge erases its data. 30 when nothing says otherwise. `restoreUrl`
|
|
166
|
+
// is where the deletion-scheduled mail sends somebody who wants their account back: an http(s) page of yours.
|
|
167
|
+
retention: { purgeAfterDays: 30, restoreUrl: "https://example.com/account/restore" },
|
|
168
|
+
// All four send by default. Turn one off by setting it to false.
|
|
169
|
+
lifecycleEmails: { accountSuspended: true, accountReinstated: true, deletionScheduled: true, deletionComplete: true },
|
|
170
|
+
});
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Mail
|
|
174
|
+
|
|
175
|
+
Four templates in `@pithy-sh/email`, all transactional, so an unsubscribe never silences them: account suspended, account reinstated, deletion scheduled, deletion complete. Each says what happened and what it means. Account suspended and deletion scheduled also say who to answer: a reply, which reaches your sending address. Account reinstated and deletion complete say nothing about who to answer; add that to your own copy if your people need it. Deletion scheduled carries the date the purge is due, and the restore button when `retention.restoreUrl` is set. Deletion complete carries the date it ran, and is sent before the address is erased. Each is written in the account's own language, dates included.
|
|
176
|
+
|
|
177
|
+
## Hooks
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
auth({
|
|
181
|
+
baseURL: "https://api.example.com",
|
|
182
|
+
onUserSuspended: async (event, d1) => {},
|
|
183
|
+
onUserReinstated: async (event, d1) => {},
|
|
184
|
+
onUserDeleted: async (event, d1) => {},
|
|
185
|
+
onUserPurged: async (event, d1) => {},
|
|
186
|
+
});
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Each fires once per transition. A call that finds the account already where it asked to put it fires nothing, and neither does restating a suspension. A hook that throws is logged and changes nothing: the transition is already written.
|
|
190
|
+
|
|
191
|
+
## Screens
|
|
192
|
+
|
|
193
|
+
Three screens ship with auth and are yours after `pithy ui add react`: account suspended, account deleted, and organization suspended. Each says what happened, what it means, and who to ask, in its own English. None renders a reason or a date from its URL, because anybody can write a URL. The details are in the mail.
|
|
194
|
+
|
|
195
|
+
## The purge contribution
|
|
196
|
+
|
|
197
|
+
A purge has to reach rows other capabilities hold, and no foreign key crosses a capability. So each capability declares how one subject's rows are erased or anonymized, and what an export hands back, on the `Capability` contract:
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
import type { PurgeContribution } from "@pithy-sh/core/src/capability/purge";
|
|
201
|
+
|
|
202
|
+
const purge: PurgeContribution = {
|
|
203
|
+
subject: "user",
|
|
204
|
+
summary: "Deletes the user's drafts.",
|
|
205
|
+
erase: async ({ subject, env }) => {
|
|
206
|
+
// Remove or anonymize this user's rows. Succeed when there is nothing left to remove.
|
|
207
|
+
},
|
|
208
|
+
export: async ({ subject, env }) => {
|
|
209
|
+
// What you hold about this user, as one JSON object. No credentials.
|
|
210
|
+
return { drafts: [] };
|
|
211
|
+
},
|
|
212
|
+
};
|
|
213
|
+
|
|
214
|
+
defineCapability({ name: "app", requiredBindings: [], purge: [purge] });
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The purge runs every composed contribution as its own step, named for its capability, so a failure retries that capability alone. That is why there is at most one per subject per capability, and why `erase` must succeed when the rows are already gone: a step is retried after a failure that may have come once they were. Any fault in `erase` is retried with the platform's backoff, because the contract makes it safe to. `export` is optional; without one, the export lists the capability as `not_exported`. A throw from it costs its own entry, never the document. The kit knows two subjects, `user` and `organization` — the second for rows scoped to a tenant, which `@pithy-sh/organization`'s purge runs ([`organization-lifecycle.md`](../../organization/docs/organization-lifecycle.md#the-purge)) — and `defineCapability` refuses a contribution for any other. Declare one on your own `app` capability for your own tables.
|
package/docs/apple-signin.md
CHANGED
|
@@ -99,7 +99,13 @@ auth({
|
|
|
99
99
|
**All three values travel as one typed JSON secret.** The Services ID, the signed JWT, and the bundle id are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-apple-credentials`:
|
|
100
100
|
|
|
101
101
|
```
|
|
102
|
-
pithy secrets create auth-apple-credentials --
|
|
102
|
+
pithy secrets create auth-apple-credentials --env <env>
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
At a terminal it asks for the value, masked. An agent or a script pipes the JSON document in on stdin instead. `--json` only shapes the output, and the value is never read from a flag:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
printf '%s' '{"clientId":"<services-id>","clientSecret":"<es256-jwt>","appBundleIdentifier":"<ios-bundle-id>"}' | pithy secrets create auth-apple-credentials --env <env>
|
|
103
109
|
```
|
|
104
110
|
|
|
105
111
|
`appBundleIdentifier` is optional. Omit it for web-only. The package reads the whole credential from the secrets store at request time and wires it into the provider. Enable Apple in config with `auth({ apple: { enabled: true } })` — no credential values in the config.
|
package/docs/facebook-oauth.md
CHANGED
|
@@ -59,7 +59,13 @@ auth({
|
|
|
59
59
|
**Both credentials travel as one typed JSON secret.** The app id and app secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-facebook-credentials`:
|
|
60
60
|
|
|
61
61
|
```
|
|
62
|
-
pithy secrets create auth-facebook-credentials --
|
|
62
|
+
pithy secrets create auth-facebook-credentials --env <env>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
At a terminal it asks for the value, masked. An agent or a script pipes the JSON document in on stdin instead. `--json` only shapes the output, and the value is never read from a flag:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
printf '%s' '{"clientId":"<your-app-id>","clientSecret":"<your-app-secret>"}' | pithy secrets create auth-facebook-credentials --env <env>
|
|
63
69
|
```
|
|
64
70
|
|
|
65
71
|
Enable Facebook in config with `auth({ facebook: { enabled: true } })` — no credential values in the config.
|
package/docs/github-oauth.md
CHANGED
|
@@ -65,7 +65,13 @@ auth({
|
|
|
65
65
|
**Both credentials travel as one typed JSON secret.** The client id and client secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-github-credentials`:
|
|
66
66
|
|
|
67
67
|
```
|
|
68
|
-
pithy secrets create auth-github-credentials --
|
|
68
|
+
pithy secrets create auth-github-credentials --env <env>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
At a terminal it asks for the value, masked. An agent or a script pipes the JSON document in on stdin instead. `--json` only shapes the output, and the value is never read from a flag:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
printf '%s' '{"clientId":"<your-client-id>","clientSecret":"<your-client-secret>"}' | pithy secrets create auth-github-credentials --env <env>
|
|
69
75
|
```
|
|
70
76
|
|
|
71
77
|
Enable GitHub in config with `auth({ github: { enabled: true } })` — no credential values in the config.
|
package/docs/google-oauth.md
CHANGED
|
@@ -83,7 +83,13 @@ auth({
|
|
|
83
83
|
**Both credentials travel as one typed JSON secret.** The client id and client secret are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-google-credentials`:
|
|
84
84
|
|
|
85
85
|
```
|
|
86
|
-
pithy secrets create auth-google-credentials --
|
|
86
|
+
pithy secrets create auth-google-credentials --env <env>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
At a terminal it asks for the value, masked. An agent or a script pipes the JSON document in on stdin instead. `--json` only shapes the output, and the value is never read from a flag:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
printf '%s' '{"clientId":"<your-client-id>","clientSecret":"<your-client-secret>"}' | pithy secrets create auth-google-credentials --env <env>
|
|
87
93
|
```
|
|
88
94
|
|
|
89
95
|
The pair stays atomic: the client id never splits off into config. The package reads the whole credential from the secrets store at request time and wires it into the provider. Enable Google in config with `auth({ google: { enabled: true } })` — no credential values in the config.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Microsoft sign-in
|
|
2
|
+
|
|
3
|
+
_This copy ships in the package because `packages/auth/src/capability.ts` sends an adopter to it by name._
|
|
4
|
+
|
|
5
|
+
Adding Microsoft to `@pithy-sh/auth`: work, school, and personal accounts, through Microsoft Entra ID. Step by step.
|
|
6
|
+
|
|
7
|
+
## Why this part is manual
|
|
8
|
+
|
|
9
|
+
An Entra ID app registration is made in the Microsoft Entra admin center by a human with access to your directory. Pithy cannot create one for you. So this is a one-time manual setup. The rest of the flow is config.
|
|
10
|
+
|
|
11
|
+
## 1. Register an application
|
|
12
|
+
|
|
13
|
+
Open the [Microsoft Entra admin center](https://entra.microsoft.com) and go to **Entra ID → App registrations → New registration**.
|
|
14
|
+
|
|
15
|
+
- **Name**: whatever your users should see on the consent screen.
|
|
16
|
+
- **Supported account types**: who may sign in. This must agree with the `tenantId` you store — see [Choose the tenant](#3-choose-the-tenant).
|
|
17
|
+
- **Redirect URI**: platform **Web**, and the exact URI from the next section.
|
|
18
|
+
|
|
19
|
+
On register you get an **Application (client) ID** and a **Directory (tenant) ID** on the overview page. Where each goes is in [Where the credentials live](#where-the-credentials-live).
|
|
20
|
+
|
|
21
|
+
## 2. The exact redirect URI
|
|
22
|
+
|
|
23
|
+
Better Auth's OAuth `redirect_uri` is always:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
<baseURL><basePath>/callback/microsoft
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
With the default `basePath` of `/auth`, the path is `/auth/callback/microsoft`. Under **Authentication → Web → Redirect URIs**, register one per environment, each on that environment's `baseURL` host:
|
|
30
|
+
|
|
31
|
+
| Environment | Redirect URI |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| dev | `http://localhost:8787/auth/callback/microsoft` |
|
|
34
|
+
| staging | `https://staging.<your-domain>/auth/callback/microsoft` |
|
|
35
|
+
| production | `https://<your-domain>/auth/callback/microsoft` |
|
|
36
|
+
|
|
37
|
+
Use your actual local port for dev — `8787` is wrangler's default, not a guarantee. Entra accepts `http://` for `localhost` only; every other host must be HTTPS. One registration can list every environment's URI, but a registration per environment keeps a staging secret from ever signing anyone into production.
|
|
38
|
+
|
|
39
|
+
### Every environment — and why feature-branch previews won't work
|
|
40
|
+
|
|
41
|
+
Entra only redirects to a URI the registration lists. Anything else is refused on Microsoft's own page, before your Worker is reached.
|
|
42
|
+
|
|
43
|
+
This bites feature-branch previews. A branch deployed to a Cloudflare preview URL — an ephemeral `*.workers.dev` or preview alias, not your registered `staging.<your-domain>` — is a host the registration has never seen, so Microsoft sign-in there fails. Add that deployment's own `<its-url>/auth/callback/microsoft` to the registration **and** point that deployment's `baseURL` at the same host, or run the flow against your registered `staging` environment instead.
|
|
44
|
+
|
|
45
|
+
Magic link and email OTP have no redirect URI — they work on any URL, preview or not. Only the OAuth providers need a registered callback.
|
|
46
|
+
|
|
47
|
+
## 3. Choose the tenant
|
|
48
|
+
|
|
49
|
+
`tenantId` says which accounts may sign in, and it must match the registration's **Supported account types**. A mismatch is refused by Microsoft, not by Pithy.
|
|
50
|
+
|
|
51
|
+
| Who signs in | Supported account types | `tenantId` |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| One organization | Accounts in this organizational directory only | the **Directory (tenant) ID** |
|
|
54
|
+
| Any work or school account | Accounts in any organizational directory | `organizations` |
|
|
55
|
+
| Work, school, and personal accounts | Accounts in any organizational directory and personal Microsoft accounts | `common` |
|
|
56
|
+
| Personal accounts only | Personal Microsoft accounts only | `consumers` |
|
|
57
|
+
|
|
58
|
+
A single-tenant app is the narrowest door, and the safest default for an internal tool. `tenantId` is required. An empty one is refused when the secret is stored, because Better Auth would otherwise fall back to `common` without saying so.
|
|
59
|
+
|
|
60
|
+
## 4. Create a client secret
|
|
61
|
+
|
|
62
|
+
Under **Certificates & secrets → Client secrets → New client secret**, pick an expiry and add it. Copy the **Value** — not the **Secret ID** — the moment it appears. Entra shows it once.
|
|
63
|
+
|
|
64
|
+
Entra client secrets expire, 24 months at the longest. Rotate before the date: add a second secret, update `auth-microsoft-credentials`, then delete the old one.
|
|
65
|
+
|
|
66
|
+
## 5. Turn on `xms_edov`
|
|
67
|
+
|
|
68
|
+
**Do this step. It is what lets a work or school address link on the first sign-in.**
|
|
69
|
+
|
|
70
|
+
Entra ID cannot vouch for an email it did not verify. A work or school ID token carries no `email_verified` claim, and its `email` is the directory's `mail` attribute — which a tenant admin can set to any string, including your customer's address at a domain they do not own. Microsoft's own claims reference says not to use it for authorization. So Pithy treats a Microsoft address as unverified unless Microsoft says otherwise.
|
|
71
|
+
|
|
72
|
+
`xms_edov` — "email domain owner verified" — is how Microsoft says otherwise. When it is `true`, the user's tenant has verified ownership of the address's domain, so the address cannot be a stranger's. It is an optional claim, off until you ask for it:
|
|
73
|
+
|
|
74
|
+
1. Open the registration and go to **Manage → Token configuration**.
|
|
75
|
+
2. Select **Add optional claim**.
|
|
76
|
+
3. Choose token type **ID**.
|
|
77
|
+
4. Tick **xms_edov**, then **Add**.
|
|
78
|
+
|
|
79
|
+
Or in **Manage → Manifest**, add it to the ID token's optional claims:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
"optionalClaims": {
|
|
83
|
+
"idToken": [{ "name": "xms_edov", "essential": false }]
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
That is the whole of it. `xms_edov` is only issued alongside an `email` claim, and Pithy requests the `email` scope, which supplies one. No claims-mapping policy is involved, so `acceptMappedClaims` stays as it is. Adding the `email` optional claim as well is harmless.
|
|
88
|
+
|
|
89
|
+
**Skip it, and here is what you get.** Every work and school address is unverified. A first Microsoft sign-in at an address that already has an account here is refused, and so is one at an address that has none — the same neutral answer either way, so nobody learns which addresses exist. The person signs in with a magic link to that address, then connects Microsoft from their account. From then on Microsoft signs them straight in. Personal accounts are unaffected, and so is anyone already connected. The cost is one magic link, once, per person.
|
|
90
|
+
|
|
91
|
+
Even with the claim on, a guest from another tenant, or an address whose domain the user's tenant has not verified, carries `xms_edov: false` and takes the same route.
|
|
92
|
+
|
|
93
|
+
## 6. Scope and profile
|
|
94
|
+
|
|
95
|
+
Pithy requests `openid`, `profile`, `email`, `User.Read`, and `offline_access` — Better Auth's defaults for Microsoft. You do not configure scopes anywhere.
|
|
96
|
+
|
|
97
|
+
Pithy does not fetch the profile photo from Microsoft Graph. Better Auth stores it in a shape the kit's image rule refuses, so it would be discarded on every sign-in. A Microsoft user starts with initials, and can set a picture in your app.
|
|
98
|
+
|
|
99
|
+
A directory user with no `mail` attribute arrives with no email at all. That sign-in is refused, because there is no address to own an account by.
|
|
100
|
+
|
|
101
|
+
## 7. Mobile
|
|
102
|
+
|
|
103
|
+
You do not register a deep-link URI with Microsoft. Microsoft only ever redirects to the Worker's `/auth/callback/microsoft`. The mobile app passes its own deep link as the sign-in `callbackURL` (for example `myapp://auth/callback`); the Worker completes the exchange and redirects there. For that to be allowed, the scheme must be listed in `trustedOrigins` (prefix match):
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
auth({
|
|
107
|
+
trustedOrigins: ["myapp://", "https://app.example.com"],
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Where the credentials live
|
|
112
|
+
|
|
113
|
+
**All three values travel as one typed JSON secret.** The client id, client secret and tenant are stored together — through `@pithy-sh/secrets`, never committed, never an env literal — as `auth-microsoft-credentials`. The tenant rides with them because it means nothing apart from the registration it belongs to:
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
pithy secrets create auth-microsoft-credentials --env <env>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
At a terminal it asks for the value, masked. An agent or a script pipes the JSON document in on stdin instead. `--json` only shapes the output, and the value is never read from a flag:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
printf '%s' '{"clientId":"<application-client-id>","clientSecret":"<client-secret-value>","tenantId":"<directory-tenant-id-or-common>"}' | pithy secrets create auth-microsoft-credentials --env <env>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Enable Microsoft in config with `auth({ microsoft: { enabled: true } })` — no credential values in the config.
|
|
126
|
+
|
|
127
|
+
## Account linking
|
|
128
|
+
|
|
129
|
+
One account per verified email. Microsoft is **not** a trusted provider, and never will be: whether its address is verified is decided per sign-in, from claims Microsoft computes and a tenant cannot write.
|
|
130
|
+
|
|
131
|
+
A Microsoft address is verified when, and only when:
|
|
132
|
+
|
|
133
|
+
- the ID token carries `xms_edov: true`, or
|
|
134
|
+
- the token's `tid` is `9188040d-6c67-4c5b-b112-36a304b66dad`, the tenant every personal Microsoft account signs in under. A personal account has no directory and no admin, and its address is the account itself, confirmed by Microsoft at sign-up, or
|
|
135
|
+
- you are connecting Microsoft from inside your account, and its address is the one your account already holds. The magic link you signed in with proved it.
|
|
136
|
+
|
|
137
|
+
Anything else is unverified: the claim absent, `false`, the string `"true"`, or an `email_verified` Entra does not issue. Absence is never read as verification.
|
|
138
|
+
|
|
139
|
+
- **Verified address → automatic link.** It links into the account at that address. No second account.
|
|
140
|
+
- **Unverified address → verify first.** It neither links nor creates an account. Sign in with a magic link to that address, then connect Microsoft from your account. If no account exists yet, the magic link creates it.
|
|
141
|
+
- **Connected → signs in on the account, not the address.** Sign-in then resolves by Microsoft's `oid`, which is immutable and never reused. A later change to the directory's `mail` attribute changes nothing.
|
|
142
|
+
|
|
143
|
+
Connecting from inside your account requires a recent sign-in, as every provider change does, and a different unverified address is refused there too.
|
|
144
|
+
|
|
145
|
+
### Turning Microsoft sign-up off
|
|
146
|
+
|
|
147
|
+
`allowSignUp` is per provider, so a project can let email create accounts while Microsoft may only sign existing ones in:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
auth({
|
|
151
|
+
disableSignUp: false, // email may create an account
|
|
152
|
+
microsoft: { enabled: true, allowSignUp: false }, // Microsoft may not
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## When the credential will not read
|
|
157
|
+
|
|
158
|
+
An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
|
|
159
|
+
|
|
160
|
+
A sign-in attempt with Microsoft then answers `503` with the code `auth/provider_unavailable` and a message naming microsoft, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two are different facts and never share an answer. The attempt is recorded in the audit trail as `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by provisioning `auth-microsoft-credentials` for that environment, or turn the provider off in config.
|
|
161
|
+
|
|
162
|
+
## Checklist
|
|
163
|
+
|
|
164
|
+
- [ ] App registration created, its **Supported account types** chosen for who should sign in.
|
|
165
|
+
- [ ] Redirect URI `<baseURL><basePath>/callback/microsoft` registered for each environment, platform **Web**.
|
|
166
|
+
- [ ] Client secret created, its **Value** copied, and its expiry on somebody's calendar.
|
|
167
|
+
- [ ] `xms_edov` added to the ID token under **Token configuration** — or the magic-link step accepted for every work and school address.
|
|
168
|
+
- [ ] Mobile deep-link scheme listed in `trustedOrigins` (no deep link in Microsoft).
|
|
169
|
+
- [ ] `clientId` + `clientSecret` + `tenantId` stored together via `pithy secrets create auth-microsoft-credentials` (typed JSON); Microsoft enabled in config with `microsoft: { enabled: true }`.
|
|
170
|
+
- [ ] Decided whether Microsoft may create accounts — `microsoft: { allowSignUp: false }` if it may not.
|
|
171
|
+
|
|
172
|
+
## Sources
|
|
173
|
+
|
|
174
|
+
- The `tid` personal-accounts value, and why `email` cannot authorize: [ID token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference).
|
|
175
|
+
- `xms_edov`, and that it requires the `email` claim: [Optional claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference).
|
|
176
|
+
- Adding an optional claim in the portal or the manifest: [Configure optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims).
|
|
177
|
+
- The logo and the words on the button: [Sign in with Microsoft branding guidelines](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-branding-in-apps).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/auth",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -42,10 +42,10 @@
|
|
|
42
42
|
"better-auth": "^1.7.11"
|
|
43
43
|
},
|
|
44
44
|
"peerDependencies": {
|
|
45
|
-
"@pithy-sh/core": "^0.
|
|
46
|
-
"@pithy-sh/email": "^0.
|
|
47
|
-
"@pithy-sh/secrets": "^0.
|
|
48
|
-
"@pithy-sh/turnstile": "^0.
|
|
45
|
+
"@pithy-sh/core": "^0.13.0",
|
|
46
|
+
"@pithy-sh/email": "^0.7.0",
|
|
47
|
+
"@pithy-sh/secrets": "^0.6.1",
|
|
48
|
+
"@pithy-sh/turnstile": "^0.6.1",
|
|
49
49
|
"hono": "^4.13.2",
|
|
50
50
|
"kysely": "^0.29.0",
|
|
51
51
|
"zod": "^4.4.0"
|
package/pithy.manifest.json
CHANGED
|
@@ -72,9 +72,22 @@
|
|
|
72
72
|
"issuer": "github",
|
|
73
73
|
"documentation": "https://github.com/settings/developers"
|
|
74
74
|
}
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"name": "auth-microsoft-credentials",
|
|
78
|
+
"origin": {
|
|
79
|
+
"kind": "obtained",
|
|
80
|
+
"issuer": "microsoft",
|
|
81
|
+
"documentation": "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
|
|
82
|
+
},
|
|
83
|
+
"rotation": {
|
|
84
|
+
"kind": "manual",
|
|
85
|
+
"issuer": "microsoft",
|
|
86
|
+
"documentation": "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
|
|
87
|
+
}
|
|
75
88
|
}
|
|
76
89
|
],
|
|
77
|
-
"whenToEnable": "Sign-in for your app — passwordless, mobile and web both first-class. Magic link, email OTP, and social sign-in with Google, Apple, Facebook, and
|
|
90
|
+
"whenToEnable": "Sign-in for your app — passwordless, mobile and web both first-class. Magic link, email OTP, and social sign-in with Google, Apple, Facebook, GitHub, and Microsoft. A successful sign-in mints a long-lived refresh session and short-lived JWT access tokens that verify locally with no database hit. It fills core's identity seams, so every other capability just calls `requireAuth()`. This is the keystone capability; add it first.",
|
|
78
91
|
"scaffold": [
|
|
79
92
|
"Create the session signing secret: `pithy secrets create auth-session-secret`.",
|
|
80
93
|
"Add the `AUTH_RATE_LIMITER` Workers Rate Limiting binding to each wrangler.jsonc env — the coarse per-IP edge guard on the auth routes. For example: `\"ratelimits\": [{ \"name\": \"AUTH_RATE_LIMITER\", \"namespace_id\": \"1001\", \"simple\": { \"limit\": 60, \"period\": 60 } }]`. This is tier 1; Better Auth's per-action limiter (tier 2) is built in.",
|
|
@@ -85,7 +98,8 @@
|
|
|
85
98
|
"Apple (optional): set `apple: { enabled: true }`, then `pithy secrets create auth-apple-credentials` with the typed JSON `{ clientId, clientSecret, appBundleIdentifier? }`. See the package's docs/apple-signin.md.",
|
|
86
99
|
"Facebook (optional): set `facebook: { enabled: true }`, then `pithy secrets create auth-facebook-credentials` with the typed JSON `{ clientId, clientSecret }`. See the package's docs/facebook-oauth.md.",
|
|
87
100
|
"GitHub (optional): set `github: { enabled: true }`, then `pithy secrets create auth-github-credentials` with the typed JSON `{ clientId, clientSecret }`. See the package's docs/github-oauth.md.",
|
|
88
|
-
"
|
|
101
|
+
"Microsoft (optional): set `microsoft: { enabled: true }`, then `pithy secrets create auth-microsoft-credentials` with the typed JSON `{ clientId, clientSecret, tenantId }`. Add the `xms_edov` optional claim to the ID token in the app registration, or every work and school address is verified by magic link before it links. See the package's docs/microsoft-oauth.md.",
|
|
102
|
+
"Looking a user up and signing them out from a dashboard is a `control-plane` surface, not an admin user, so the routes under /auth/admin are reached with a signed management credential rather than a session. Add `controlplane()` to this Worker and run `pithy dashboard connect`, then grant the connection only what its tooling needs: `auth:users:read` to find people, `auth:devices:read` to walk the device registry, `auth:sessions:revoke` to kill one stolen session, `auth:users:logout` to sign somebody out everywhere, `auth:devices:revoke` for a phone reported lost, and the account lifecycle's three: `auth:users:suspend` to suspend somebody and reinstate them, `auth:users:delete`, `auth:users:export`. Eight scopes and not one admin flag — a support tool that looks people up must not also be able to sign the customer base out, and an incident-response tool that kills a session has no business reading every address in the user table. With the seam not composed every /auth/admin route answers `controlplane/not_connected`, and no app session opens any of them whatever it carries. There is deliberately no impersonation: signing in as a user produces a credential indistinguishable from theirs, so it is excluded until it has its own design and security review."
|
|
89
103
|
],
|
|
90
104
|
"configOptions": [
|
|
91
105
|
{
|
|
@@ -97,7 +111,7 @@
|
|
|
97
111
|
"key": "baseURL",
|
|
98
112
|
"default": "https://api.example.com",
|
|
99
113
|
"constant": "publicOrigin",
|
|
100
|
-
"describe": "The public origin of this Worker where it is deployed, no trailing slash. OAuth callbacks, JWKS and magic-link URLs are built from it, so it must be reachable. A `dev` composition ignores it and serves on `http://<the host the request arrived at>` — local dev has no TLS and its port is assigned per run, so it is the one address nobody can write down. Set `trustedOrigins` and the social providers (`google`, `apple`, `facebook`, `github`) by hand — see the scaffold steps below."
|
|
114
|
+
"describe": "The public origin of this Worker where it is deployed, no trailing slash. OAuth callbacks, JWKS and magic-link URLs are built from it, so it must be reachable. A `dev` composition ignores it and serves on `http://<the host the request arrived at>` — local dev has no TLS and its port is assigned per run, so it is the one address nobody can write down. Set `trustedOrigins` and the social providers (`google`, `apple`, `facebook`, `github`, `microsoft`) by hand — see the scaffold steps below."
|
|
101
115
|
},
|
|
102
116
|
{
|
|
103
117
|
"key": "disableSignUp",
|