@pithy-sh/auth 0.9.0 → 0.10.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/audit/actions.d.ts +21 -0
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +22 -1
- package/dist/audit/emit.js +1 -1
- package/dist/capability.d.ts +26 -1
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +23 -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 +28 -2
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -3
- package/dist/data/userLifecycle.d.ts +61 -0
- package/dist/data/userLifecycle.d.ts.map +1 -0
- package/dist/data/userLifecycle.js +50 -0
- package/dist/http/guards.d.ts +23 -1
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +28 -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 +5 -0
- package/dist/http/middleware.d.ts.map +1 -1
- package/dist/http/middleware.js +47 -6
- 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/routes.d.ts.map +1 -1
- package/dist/http/routes.js +20 -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/enforce.d.ts +40 -0
- package/dist/lifecycle/enforce.d.ts.map +1 -0
- package/dist/lifecycle/enforce.js +70 -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/request.d.ts +15 -0
- package/dist/lifecycle/request.d.ts.map +1 -0
- package/dist/lifecycle/request.js +27 -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 +132 -0
- package/dist/lifecycle/transitions.d.ts.map +1 -0
- package/dist/lifecycle/transitions.js +349 -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/set.d.ts +2 -1
- package/dist/migrations/set.d.ts.map +1 -1
- package/dist/migrations/set.js +4 -2
- package/dist/peer.d.ts +4 -0
- package/dist/peer.d.ts.map +1 -1
- 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 +105 -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 +23 -0
- package/src/audit/emit.ts +1 -1
- package/src/capability.ts +125 -54
- 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 +80 -0
- package/src/http/guards.ts +29 -1
- package/src/http/lifecycleGate.ts +78 -0
- package/src/http/middleware.ts +61 -2
- package/src/http/providerRefusal.ts +10 -0
- package/src/http/resolve.ts +8 -3
- package/src/http/routes.ts +38 -1
- package/src/instance/auth.ts +69 -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/enforce.ts +89 -0
- package/src/lifecycle/hooks.ts +54 -0
- package/src/lifecycle/request.ts +31 -0
- package/src/lifecycle/state.ts +101 -0
- package/src/lifecycle/transitions.ts +483 -0
- package/src/migrations/0004_user_lifecycle.ts +68 -0
- package/src/migrations/set.ts +3 -1
- package/src/test-utils/liveApp.ts +2 -1
- package/src/test-utils/scopedBackend.ts +2 -1
- package/src/version.generated.ts +1 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"liveApp.d.ts","sourceRoot":"","sources":["../../src/test-utils/liveApp.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAuB3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iHAAiH;AACjH,eAAO,MAAM,aAAa
|
|
1
|
+
{"version":3,"file":"liveApp.d.ts","sourceRoot":"","sources":["../../src/test-utils/liveApp.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAuB3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iHAAiH;AACjH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0D,CAAC;AAErF,4GAA4G;AAC5G,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAyBD,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAChE,yGAAyG;IACzG,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7E;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO;IACtB,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;IACjB,mGAAmG;IACnG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,mDAAmD;IACnD,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,0GAA0G;IAC1G,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACrC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,yFAAyF;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAyF5E"}
|
|
@@ -125,6 +125,27 @@ export declare const SCOPED_REGISTRY: {
|
|
|
125
125
|
readonly documentation: "https://github.com/settings/developers";
|
|
126
126
|
};
|
|
127
127
|
};
|
|
128
|
+
"auth-microsoft-credentials": {
|
|
129
|
+
readonly backend: "d1";
|
|
130
|
+
readonly scope: "environment";
|
|
131
|
+
readonly rotatable: true;
|
|
132
|
+
readonly valueType: "json";
|
|
133
|
+
readonly schema: import("zod").ZodObject<{
|
|
134
|
+
clientId: import("zod").ZodString;
|
|
135
|
+
clientSecret: import("zod").ZodString;
|
|
136
|
+
tenantId: import("zod").ZodString;
|
|
137
|
+
}, import("zod/v4/core").$strip>;
|
|
138
|
+
readonly origin: {
|
|
139
|
+
readonly kind: "obtained";
|
|
140
|
+
readonly issuer: "microsoft";
|
|
141
|
+
readonly documentation: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade";
|
|
142
|
+
};
|
|
143
|
+
readonly rotation: {
|
|
144
|
+
readonly kind: "manual";
|
|
145
|
+
readonly issuer: "microsoft";
|
|
146
|
+
readonly documentation: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade";
|
|
147
|
+
};
|
|
148
|
+
};
|
|
128
149
|
"email-link-signing-key": {
|
|
129
150
|
readonly backend: "cf-secrets-store";
|
|
130
151
|
readonly scope: "environment";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scopedBackend.d.ts","sourceRoot":"","sources":["../../src/test-utils/scopedBackend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAM5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,iDAAiD,CAAC;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQlD;;;;;;;;;;GAUG;AAEH,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,4CAA4C,CAAC;AAE/E,6FAA6F;AAC7F,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,+FAA+F;AAC/F,eAAO,MAAM,eAAe
|
|
1
|
+
{"version":3,"file":"scopedBackend.d.ts","sourceRoot":"","sources":["../../src/test-utils/scopedBackend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAM5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,iDAAiD,CAAC;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQlD;;;;;;;;;;GAUG;AAEH,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,4CAA4C,CAAC;AAE/E,6FAA6F;AAC7F,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,+FAA+F;AAC/F,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAsD,CAAC;AAEnF,gHAAgH;AAChH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,OAAO,eAAe,CAQhE,CAAC;AAEF,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,eAAe,GAAG;IAAE,EAAE,EAAE,UAAU,CAAA;CAAE,EACzC,KAAK,GAAE,SAAS,eAAe,EAAO,GACrC,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,GAAE,OAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS3G;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,UAAU,EACd,OAAO,SAAoB,GAC1B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B5C"}
|
|
@@ -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.10.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.10.0";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -0,0 +1,105 @@
|
|
|
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. The routes that suspend, delete, restore and export arrive with their own issues, and so does the purge that erases a deleted account's data: the suspend routes with #621, the delete, restore and export routes and the purge Workflow with #622. This page is the seam they are built on.
|
|
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, or when the purge erases it. The purge arrives with #622; until then a deleted account stays deleted and its rows stay where they are. |
|
|
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 will leave 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. 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
|
+
Each transition also writes an audit event: `auth/admin_user_suspended`, `auth/admin_user_reinstated`, `auth/admin_user_soft_deleted`, `auth/admin_user_restored`, `auth/admin_user_purged`, and `auth/user_self_deleted` when the account's holder deletes it.
|
|
42
|
+
|
|
43
|
+
## Scopes
|
|
44
|
+
|
|
45
|
+
Reading a user, ending their access, and erasing them are three grants, beside `auth:users:read`:
|
|
46
|
+
|
|
47
|
+
- `auth:users:suspend` — suspend and reinstate.
|
|
48
|
+
- `auth:users:delete` — delete, restore, and start a purge.
|
|
49
|
+
- `auth:users:export` — everything the kit holds about one account, for an access request.
|
|
50
|
+
|
|
51
|
+
None of them is implied by another. See [CONTROL-PLANE.md](../../../docs/CONTROL-PLANE.md) for how a connection is granted one.
|
|
52
|
+
|
|
53
|
+
## Config
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
auth({
|
|
57
|
+
baseURL: "https://api.example.com",
|
|
58
|
+
// How long a deleted account waits before the purge erases its data (the purge lands in #622). 30 when nothing says otherwise.
|
|
59
|
+
retention: { purgeAfterDays: 30 },
|
|
60
|
+
// All four send by default. Turn one off by setting it to false.
|
|
61
|
+
lifecycleEmails: { accountSuspended: true, accountReinstated: true, deletionScheduled: true, deletionComplete: true },
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Mail
|
|
66
|
+
|
|
67
|
+
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. Deletion complete carries the date it ran. Each is written in the account's own language, dates included.
|
|
68
|
+
|
|
69
|
+
## Hooks
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
auth({
|
|
73
|
+
baseURL: "https://api.example.com",
|
|
74
|
+
onUserSuspended: async (event, d1) => {},
|
|
75
|
+
onUserReinstated: async (event, d1) => {},
|
|
76
|
+
onUserDeleted: async (event, d1) => {},
|
|
77
|
+
onUserPurged: async (event, d1) => {},
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Each fires once per transition. A call that finds the account already where it asked to put it fires nothing. A hook that throws is logged and changes nothing: the transition is already written.
|
|
82
|
+
|
|
83
|
+
## Screens
|
|
84
|
+
|
|
85
|
+
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.
|
|
86
|
+
|
|
87
|
+
## The purge contribution
|
|
88
|
+
|
|
89
|
+
A hard delete 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, on the `Capability` contract:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import type { PurgeContribution } from "@pithy-sh/core/src/capability/purge";
|
|
93
|
+
|
|
94
|
+
const purge: PurgeContribution = {
|
|
95
|
+
subject: "user",
|
|
96
|
+
summary: "Deletes the user's drafts.",
|
|
97
|
+
erase: async ({ subject, env }) => {
|
|
98
|
+
// Remove or anonymize this user's rows. Succeed when there is nothing left to remove.
|
|
99
|
+
},
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
defineCapability({ name: "app", requiredBindings: [], purge: [purge] });
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Today the kit declares the contract and the window, and nothing calls `erase` yet. The purge Workflow arrives with #622. It will run 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. `defineCapability` refuses a contribution for a subject the kit does not know. 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.10.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.12.0",
|
|
46
|
+
"@pithy-sh/email": "^0.6.0",
|
|
47
|
+
"@pithy-sh/secrets": "^0.6.0",
|
|
48
|
+
"@pithy-sh/turnstile": "^0.6.0",
|
|
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`, `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",
|
package/src/audit/actions.ts
CHANGED
|
@@ -150,6 +150,29 @@ export const AuthAuditActions = {
|
|
|
150
150
|
adminUserSessionsRevoked: "auth/admin_user_sessions_revoked",
|
|
151
151
|
/** One of a user's devices was signed out and its registration dropped, from the management surface. */
|
|
152
152
|
adminDeviceRevoked: "auth/admin_device_revoked",
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* The account lifecycle (#620). Each is written by the transition in `../lifecycle/transitions.ts`, beside
|
|
156
|
+
* the `pithy_auth_user_lifecycle` row that records the same fact — the trail answers "who, from where", the
|
|
157
|
+
* table answers "what happened to this account". The admin ones carry `actorType: "control-plane"`; the
|
|
158
|
+
* self-service deletion carries the account's own holder, and the purge `system`.
|
|
159
|
+
*
|
|
160
|
+
* The dashboard's own `customer/user_suspended` and `customer/user_restored` are the client side of the
|
|
161
|
+
* same events, recorded where the operator pressed the button.
|
|
162
|
+
*/
|
|
163
|
+
|
|
164
|
+
/** An account was suspended from the management surface. Carries the reason and any end date. */
|
|
165
|
+
adminUserSuspended: "auth/admin_user_suspended",
|
|
166
|
+
/** A suspended account was reinstated from the management surface. */
|
|
167
|
+
adminUserReinstated: "auth/admin_user_reinstated",
|
|
168
|
+
/** An account was deleted from the management surface, with its purge window starting now. */
|
|
169
|
+
adminUserSoftDeleted: "auth/admin_user_soft_deleted",
|
|
170
|
+
/** A deleted account was restored inside its purge window, from the management surface. */
|
|
171
|
+
adminUserRestored: "auth/admin_user_restored",
|
|
172
|
+
/** A deleted account's data was erased. Recorded once, when the last purge step has run. */
|
|
173
|
+
adminUserPurged: "auth/admin_user_purged",
|
|
174
|
+
/** The account's own holder deleted their account. Always a soft deletion, on the configured window. */
|
|
175
|
+
userSelfDeleted: "auth/user_self_deleted",
|
|
153
176
|
} as const;
|
|
154
177
|
|
|
155
178
|
/** One of the auth audit action codes. */
|
package/src/audit/emit.ts
CHANGED
|
@@ -431,7 +431,7 @@ export const ProviderAccount = z
|
|
|
431
431
|
.object({
|
|
432
432
|
id: z.string().describe("The account row's primary key — which link was made or broken."),
|
|
433
433
|
userId: z.string().describe("The user this provider can, or could, sign in as."),
|
|
434
|
-
providerId: z.string().describe("The provider slug (`google`, `apple`, `facebook`, `github`)."),
|
|
434
|
+
providerId: z.string().describe("The provider slug (`google`, `apple`, `facebook`, `github`, `microsoft`)."),
|
|
435
435
|
})
|
|
436
436
|
.describe("The account-row columns `auth/oauth_linked` and `auth/oauth_unlinked` are built from.");
|
|
437
437
|
export type ProviderAccount = z.output<typeof ProviderAccount>;
|