@pithy-sh/auth 0.15.3 → 0.17.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.
Files changed (209) hide show
  1. package/README.md +4 -0
  2. package/dist/attestation/appAttest/assertion.d.ts +32 -0
  3. package/dist/attestation/appAttest/assertion.d.ts.map +1 -0
  4. package/dist/attestation/appAttest/assertion.js +59 -0
  5. package/dist/attestation/appAttest/attestation.d.ts +49 -0
  6. package/dist/attestation/appAttest/attestation.d.ts.map +1 -0
  7. package/dist/attestation/appAttest/attestation.js +111 -0
  8. package/dist/attestation/appAttest/authData.d.ts +24 -0
  9. package/dist/attestation/appAttest/authData.d.ts.map +1 -0
  10. package/dist/attestation/appAttest/authData.js +32 -0
  11. package/dist/attestation/appAttest/base64.d.ts +8 -0
  12. package/dist/attestation/appAttest/base64.d.ts.map +1 -0
  13. package/dist/attestation/appAttest/base64.js +27 -0
  14. package/dist/attestation/appAttest/bytes.d.ts +7 -0
  15. package/dist/attestation/appAttest/bytes.d.ts.map +1 -0
  16. package/dist/attestation/appAttest/bytes.js +19 -0
  17. package/dist/attestation/appAttest/cbor.d.ts +20 -0
  18. package/dist/attestation/appAttest/cbor.d.ts.map +1 -0
  19. package/dist/attestation/appAttest/cbor.js +96 -0
  20. package/dist/attestation/appAttest/der.d.ts +38 -0
  21. package/dist/attestation/appAttest/der.d.ts.map +1 -0
  22. package/dist/attestation/appAttest/der.js +106 -0
  23. package/dist/attestation/appAttest/keys.d.ts +15 -0
  24. package/dist/attestation/appAttest/keys.d.ts.map +1 -0
  25. package/dist/attestation/appAttest/keys.js +37 -0
  26. package/dist/attestation/appAttest/root.d.ts +9 -0
  27. package/dist/attestation/appAttest/root.d.ts.map +1 -0
  28. package/dist/attestation/appAttest/root.js +12 -0
  29. package/dist/attestation/appAttest/verifier.d.ts +39 -0
  30. package/dist/attestation/appAttest/verifier.d.ts.map +1 -0
  31. package/dist/attestation/appAttest/verifier.js +121 -0
  32. package/dist/attestation/appAttest/x509.d.ts +50 -0
  33. package/dist/attestation/appAttest/x509.d.ts.map +1 -0
  34. package/dist/attestation/appAttest/x509.js +163 -0
  35. package/dist/attestation/challenge.d.ts +26 -0
  36. package/dist/attestation/challenge.d.ts.map +1 -0
  37. package/dist/attestation/challenge.js +47 -0
  38. package/dist/attestation/config.d.ts +72 -0
  39. package/dist/attestation/config.d.ts.map +1 -0
  40. package/dist/attestation/config.js +52 -0
  41. package/dist/attestation/errors.d.ts +30 -0
  42. package/dist/attestation/errors.d.ts.map +1 -0
  43. package/dist/attestation/errors.js +45 -0
  44. package/dist/attestation/gate.d.ts +27 -0
  45. package/dist/attestation/gate.d.ts.map +1 -0
  46. package/dist/attestation/gate.js +78 -0
  47. package/dist/attestation/playIntegrity/google.d.ts +47 -0
  48. package/dist/attestation/playIntegrity/google.d.ts.map +1 -0
  49. package/dist/attestation/playIntegrity/google.js +178 -0
  50. package/dist/attestation/playIntegrity/verdict.d.ts +40 -0
  51. package/dist/attestation/playIntegrity/verdict.d.ts.map +1 -0
  52. package/dist/attestation/playIntegrity/verdict.js +93 -0
  53. package/dist/attestation/playIntegrity/verifier.d.ts +22 -0
  54. package/dist/attestation/playIntegrity/verifier.d.ts.map +1 -0
  55. package/dist/attestation/playIntegrity/verifier.js +64 -0
  56. package/dist/attestation/verifier.d.ts +60 -0
  57. package/dist/attestation/verifier.d.ts.map +1 -0
  58. package/dist/attestation/verifier.js +46 -0
  59. package/dist/attestation/wire.d.ts +42 -0
  60. package/dist/attestation/wire.d.ts.map +1 -0
  61. package/dist/attestation/wire.js +72 -0
  62. package/dist/capability.d.ts +49 -6
  63. package/dist/capability.d.ts.map +1 -1
  64. package/dist/capability.js +42 -7
  65. package/dist/client/api.d.ts +37 -24
  66. package/dist/client/api.d.ts.map +1 -1
  67. package/dist/client/api.js +52 -41
  68. package/dist/client/attestation.d.ts +148 -0
  69. package/dist/client/attestation.d.ts.map +1 -0
  70. package/dist/client/attestation.js +321 -0
  71. package/dist/client/projection.d.ts +29 -4
  72. package/dist/client/projection.d.ts.map +1 -1
  73. package/dist/data/appAttestKey.d.ts +30 -0
  74. package/dist/data/appAttestKey.d.ts.map +1 -0
  75. package/dist/data/appAttestKey.js +25 -0
  76. package/dist/data/attestationChallenge.d.ts +17 -0
  77. package/dist/data/attestationChallenge.d.ts.map +1 -0
  78. package/dist/data/attestationChallenge.js +19 -0
  79. package/dist/data/tables.d.ts +19 -1
  80. package/dist/data/tables.d.ts.map +1 -1
  81. package/dist/data/tables.js +6 -2
  82. package/dist/data/userLifecycle.d.ts +1 -0
  83. package/dist/data/userLifecycle.d.ts.map +1 -1
  84. package/dist/data/userLifecycle.js +3 -2
  85. package/dist/hooks/runtime.d.ts +32 -0
  86. package/dist/hooks/runtime.d.ts.map +1 -0
  87. package/dist/hooks/runtime.js +25 -0
  88. package/dist/http/adminRoutes.d.ts.map +1 -1
  89. package/dist/http/adminRoutes.js +4 -2
  90. package/dist/http/devLoginRoute.js +3 -3
  91. package/dist/http/resolve.d.ts.map +1 -1
  92. package/dist/http/resolve.js +3 -2
  93. package/dist/http/responses.d.ts +15 -0
  94. package/dist/http/responses.d.ts.map +1 -1
  95. package/dist/http/responses.js +13 -2
  96. package/dist/http/routes.d.ts +5 -1
  97. package/dist/http/routes.d.ts.map +1 -1
  98. package/dist/http/routes.js +92 -25
  99. package/dist/http/schemas.d.ts +7 -0
  100. package/dist/http/schemas.d.ts.map +1 -1
  101. package/dist/http/schemas.js +7 -1
  102. package/dist/index.js +1 -1
  103. package/dist/instance/secrets.d.ts +86 -7
  104. package/dist/instance/secrets.d.ts.map +1 -1
  105. package/dist/instance/secrets.js +54 -8
  106. package/dist/lifecycle/erasure.d.ts.map +1 -1
  107. package/dist/lifecycle/erasure.js +2 -1
  108. package/dist/lifecycle/hooks.d.ts +18 -10
  109. package/dist/lifecycle/hooks.d.ts.map +1 -1
  110. package/dist/lifecycle/request.d.ts +2 -1
  111. package/dist/lifecycle/request.d.ts.map +1 -1
  112. package/dist/lifecycle/request.js +4 -1
  113. package/dist/lifecycle/transitions.d.ts +24 -16
  114. package/dist/lifecycle/transitions.d.ts.map +1 -1
  115. package/dist/lifecycle/transitions.js +27 -16
  116. package/dist/migrations/0009_attestation_challenges.d.ts +9 -0
  117. package/dist/migrations/0009_attestation_challenges.d.ts.map +1 -0
  118. package/dist/migrations/0009_attestation_challenges.js +21 -0
  119. package/dist/migrations/0010_app_attest_keys.d.ts +9 -0
  120. package/dist/migrations/0010_app_attest_keys.d.ts.map +1 -0
  121. package/dist/migrations/0010_app_attest_keys.js +17 -0
  122. package/dist/migrations/0011_retained_basis_key.d.ts +10 -0
  123. package/dist/migrations/0011_retained_basis_key.d.ts.map +1 -0
  124. package/dist/migrations/0011_retained_basis_key.js +18 -0
  125. package/dist/migrations/set.d.ts +4 -1
  126. package/dist/migrations/set.d.ts.map +1 -1
  127. package/dist/migrations/set.js +8 -2
  128. package/dist/purge/run.d.ts +11 -11
  129. package/dist/purge/run.d.ts.map +1 -1
  130. package/dist/purge/run.js +9 -8
  131. package/dist/purge/workflow.d.ts +7 -1
  132. package/dist/purge/workflow.d.ts.map +1 -1
  133. package/dist/purge/workflow.js +6 -2
  134. package/dist/seeds/devSession.js +1 -1
  135. package/dist/test-utils/appAttestDevice.d.ts +92 -0
  136. package/dist/test-utils/appAttestDevice.d.ts.map +1 -0
  137. package/dist/test-utils/appAttestDevice.js +282 -0
  138. package/dist/test-utils/appAttestSample.d.ts +22 -0
  139. package/dist/test-utils/appAttestSample.d.ts.map +1 -0
  140. package/dist/test-utils/appAttestSample.js +24 -0
  141. package/dist/test-utils/googlePlay.d.ts +47 -0
  142. package/dist/test-utils/googlePlay.d.ts.map +1 -0
  143. package/dist/test-utils/googlePlay.js +117 -0
  144. package/dist/test-utils/liveApp.d.ts +76 -36
  145. package/dist/test-utils/liveApp.d.ts.map +1 -1
  146. package/dist/test-utils/liveApp.js +16 -5
  147. package/dist/test-utils/rollbackThrough.d.ts +11 -0
  148. package/dist/test-utils/rollbackThrough.d.ts.map +1 -0
  149. package/dist/test-utils/rollbackThrough.js +16 -0
  150. package/dist/test-utils/scopedBackend.d.ts +25 -0
  151. package/dist/test-utils/scopedBackend.d.ts.map +1 -1
  152. package/dist/test-utils/scopedBackend.js +1 -1
  153. package/dist/version.generated.d.ts +1 -1
  154. package/dist/version.generated.js +1 -1
  155. package/docs/account-lifecycle.md +46 -10
  156. package/docs/attestation.md +173 -0
  157. package/package.json +5 -5
  158. package/pithy.manifest.json +14 -0
  159. package/src/attestation/appAttest/assertion.ts +65 -0
  160. package/src/attestation/appAttest/attestation.ts +159 -0
  161. package/src/attestation/appAttest/authData.ts +45 -0
  162. package/src/attestation/appAttest/base64.ts +29 -0
  163. package/src/attestation/appAttest/bytes.ts +18 -0
  164. package/src/attestation/appAttest/cbor.ts +116 -0
  165. package/src/attestation/appAttest/der.ts +126 -0
  166. package/src/attestation/appAttest/keys.ts +57 -0
  167. package/src/attestation/appAttest/root.ts +13 -0
  168. package/src/attestation/appAttest/verifier.ts +113 -0
  169. package/src/attestation/appAttest/x509.ts +209 -0
  170. package/src/attestation/challenge.ts +56 -0
  171. package/src/attestation/config.ts +118 -0
  172. package/src/attestation/errors.ts +60 -0
  173. package/src/attestation/gate.ts +105 -0
  174. package/src/attestation/playIntegrity/google.ts +239 -0
  175. package/src/attestation/playIntegrity/verdict.ts +149 -0
  176. package/src/attestation/playIntegrity/verifier.ts +77 -0
  177. package/src/attestation/verifier.ts +87 -0
  178. package/src/attestation/wire.ts +79 -0
  179. package/src/capability.ts +85 -16
  180. package/src/client/api.ts +73 -40
  181. package/src/client/attestation.ts +404 -0
  182. package/src/client/projection.ts +29 -4
  183. package/src/data/appAttestKey.ts +45 -0
  184. package/src/data/attestationChallenge.ts +23 -0
  185. package/src/data/tables.ts +5 -1
  186. package/src/data/userLifecycle.ts +9 -2
  187. package/src/hooks/runtime.ts +41 -0
  188. package/src/http/adminRoutes.ts +14 -7
  189. package/src/http/resolve.ts +8 -4
  190. package/src/http/responses.ts +29 -1
  191. package/src/http/routes.ts +128 -38
  192. package/src/http/schemas.ts +24 -0
  193. package/src/instance/secrets.ts +88 -9
  194. package/src/lifecycle/erasure.ts +2 -1
  195. package/src/lifecycle/hooks.ts +22 -10
  196. package/src/lifecycle/request.ts +4 -1
  197. package/src/lifecycle/transitions.ts +47 -28
  198. package/src/migrations/0009_attestation_challenges.ts +28 -0
  199. package/src/migrations/0010_app_attest_keys.ts +27 -0
  200. package/src/migrations/0011_retained_basis_key.ts +19 -0
  201. package/src/migrations/set.ts +7 -1
  202. package/src/purge/run.ts +29 -17
  203. package/src/purge/workflow.ts +7 -3
  204. package/src/test-utils/appAttestDevice.ts +399 -0
  205. package/src/test-utils/appAttestSample.ts +20 -0
  206. package/src/test-utils/googlePlay.ts +144 -0
  207. package/src/test-utils/liveApp.ts +31 -5
  208. package/src/test-utils/rollbackThrough.ts +24 -0
  209. package/src/version.generated.ts +1 -1
@@ -2,8 +2,11 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import type { D1Database } from "@cloudflare/workers-types";
4
4
  import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
5
+ import type { z } from "zod";
6
+ import type { AttestationConfig } from "../attestation/config";
7
+ import { type PlayIntegrityServiceAccount } from "../instance/secrets";
5
8
  /**
6
- * A real auth Worker on a real port, for the live suites (#84).
9
+ * A real auth Worker on a real port, for the live suites.
7
10
  *
8
11
  * The live E2E questions this package has are about an **origin**: which `redirect_uri` Better Auth
9
12
  * hands Google, whether a token posted from a browser survives the humanity gate, whether a callback
@@ -17,7 +20,7 @@ import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
17
20
  *
18
21
  * - **Miniflare supplies D1**, from Node rather than from inside a worker. Two databases, as a deployed
19
22
  * worker has: `DB` for the `pithy_auth_*` and `pithy_email_*` tables, `SECRETS` for the encrypted
20
- * rows every secret is read from (#153). No plaintext binding stands in for either.
23
+ * rows every secret is read from. No plaintext binding stands in for either.
21
24
  * - **The migrations are the real ones**, run through the real registry and runner.
22
25
  * - **`node:http` gives the port.** Vitest's `fetch` reaches the app the way a browser would, so an
23
26
  * `Origin` header is a real one and a `Set-Cookie` is a real one.
@@ -55,10 +58,10 @@ export declare const LIVE_REGISTRY: {
55
58
  readonly scope: "environment";
56
59
  readonly rotatable: false;
57
60
  readonly valueType: "json";
58
- readonly schema: import("zod").ZodObject<{
59
- clientId: import("zod").ZodString;
60
- clientSecret: import("zod").ZodString;
61
- }, import("zod/v4/core").$strip>;
61
+ readonly schema: z.ZodObject<{
62
+ clientId: z.ZodString;
63
+ clientSecret: z.ZodString;
64
+ }, z.core.$strip>;
62
65
  readonly origin: {
63
66
  readonly kind: "obtained";
64
67
  readonly issuer: "google";
@@ -75,11 +78,11 @@ export declare const LIVE_REGISTRY: {
75
78
  readonly scope: "environment";
76
79
  readonly rotatable: true;
77
80
  readonly valueType: "json";
78
- readonly schema: import("zod").ZodObject<{
79
- clientId: import("zod").ZodString;
80
- clientSecret: import("zod").ZodString;
81
- appBundleIdentifier: import("zod").ZodOptional<import("zod").ZodString>;
82
- }, import("zod/v4/core").$strip>;
81
+ readonly schema: z.ZodObject<{
82
+ clientId: z.ZodString;
83
+ clientSecret: z.ZodString;
84
+ appBundleIdentifier: z.ZodOptional<z.ZodString>;
85
+ }, z.core.$strip>;
83
86
  readonly origin: {
84
87
  readonly kind: "obtained";
85
88
  readonly issuer: "apple";
@@ -96,10 +99,10 @@ export declare const LIVE_REGISTRY: {
96
99
  readonly scope: "environment";
97
100
  readonly rotatable: false;
98
101
  readonly valueType: "json";
99
- readonly schema: import("zod").ZodObject<{
100
- clientId: import("zod").ZodString;
101
- clientSecret: import("zod").ZodString;
102
- }, import("zod/v4/core").$strip>;
102
+ readonly schema: z.ZodObject<{
103
+ clientId: z.ZodString;
104
+ clientSecret: z.ZodString;
105
+ }, z.core.$strip>;
103
106
  readonly origin: {
104
107
  readonly kind: "obtained";
105
108
  readonly issuer: "facebook";
@@ -116,10 +119,10 @@ export declare const LIVE_REGISTRY: {
116
119
  readonly scope: "environment";
117
120
  readonly rotatable: false;
118
121
  readonly valueType: "json";
119
- readonly schema: import("zod").ZodObject<{
120
- clientId: import("zod").ZodString;
121
- clientSecret: import("zod").ZodString;
122
- }, import("zod/v4/core").$strip>;
122
+ readonly schema: z.ZodObject<{
123
+ clientId: z.ZodString;
124
+ clientSecret: z.ZodString;
125
+ }, z.core.$strip>;
123
126
  readonly origin: {
124
127
  readonly kind: "obtained";
125
128
  readonly issuer: "github";
@@ -136,11 +139,11 @@ export declare const LIVE_REGISTRY: {
136
139
  readonly scope: "environment";
137
140
  readonly rotatable: true;
138
141
  readonly valueType: "json";
139
- readonly schema: import("zod").ZodObject<{
140
- clientId: import("zod").ZodString;
141
- clientSecret: import("zod").ZodString;
142
- tenantId: import("zod").ZodString;
143
- }, import("zod/v4/core").$strip>;
142
+ readonly schema: z.ZodObject<{
143
+ clientId: z.ZodString;
144
+ clientSecret: z.ZodString;
145
+ tenantId: z.ZodString;
146
+ }, z.core.$strip>;
144
147
  readonly origin: {
145
148
  readonly kind: "obtained";
146
149
  readonly issuer: "microsoft";
@@ -152,21 +155,46 @@ export declare const LIVE_REGISTRY: {
152
155
  readonly documentation: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade";
153
156
  };
154
157
  };
158
+ "auth-play-integrity-service-account": {
159
+ readonly backend: "d1";
160
+ readonly scope: "environment";
161
+ readonly rotatable: false;
162
+ readonly valueType: "json";
163
+ readonly schema: z.ZodObject<{
164
+ type: z.ZodOptional<z.ZodLiteral<"service_account">>;
165
+ project_id: z.ZodOptional<z.ZodString>;
166
+ private_key_id: z.ZodOptional<z.ZodString>;
167
+ private_key: z.ZodString;
168
+ client_email: z.ZodString;
169
+ client_id: z.ZodOptional<z.ZodString>;
170
+ token_uri: z.ZodOptional<z.ZodString>;
171
+ }, z.core.$strip>;
172
+ readonly origin: {
173
+ readonly kind: "obtained";
174
+ readonly issuer: "google";
175
+ readonly documentation: "https://console.cloud.google.com/iam-admin/serviceaccounts";
176
+ };
177
+ readonly rotation: {
178
+ readonly kind: "manual";
179
+ readonly issuer: "google";
180
+ readonly documentation: "https://console.cloud.google.com/iam-admin/serviceaccounts";
181
+ };
182
+ };
155
183
  "turnstile-secret-keys": {
156
184
  readonly backend: "d1";
157
185
  readonly scope: "environment";
158
186
  readonly rotatable: true;
159
187
  readonly valueType: "json";
160
- readonly schema: import("zod").ZodObject<{
161
- visible: import("zod").ZodOptional<import("zod").ZodObject<{
162
- key: import("zod").ZodString;
163
- lastRotatedAt: import("zod").ZodOptional<import("zod").ZodString>;
164
- }, import("zod/v4/core").$strip>>;
165
- invisible: import("zod").ZodOptional<import("zod").ZodObject<{
166
- key: import("zod").ZodString;
167
- lastRotatedAt: import("zod").ZodOptional<import("zod").ZodString>;
168
- }, import("zod/v4/core").$strip>>;
169
- }, import("zod/v4/core").$strict>;
188
+ readonly schema: z.ZodObject<{
189
+ visible: z.ZodOptional<z.ZodObject<{
190
+ key: z.ZodString;
191
+ lastRotatedAt: z.ZodOptional<z.ZodString>;
192
+ }, z.core.$strip>>;
193
+ invisible: z.ZodOptional<z.ZodObject<{
194
+ key: z.ZodString;
195
+ lastRotatedAt: z.ZodOptional<z.ZodString>;
196
+ }, z.core.$strip>>;
197
+ }, z.core.$strict>;
170
198
  readonly origin: {
171
199
  readonly kind: "obtained";
172
200
  readonly issuer: "cloudflare";
@@ -214,10 +242,22 @@ export interface LiveAppOptions {
214
242
  * stanza. `dev` by default, because that is what these suites are: a developer's machine, running the
215
243
  * stack the way `pithy dev` does.
216
244
  *
217
- * It is an option because one thing now reads it — the turnstile gate refuses a Cloudflare test key
218
- * outside dev and staging (#374) — so a suite has to be able to say it is prod to prove that.
245
+ * It is an option because the turnstile gate refuses a Cloudflare test key
246
+ * outside dev and staging — so a suite has to be able to say it is prod to prove that.
219
247
  */
220
248
  environment?: string;
249
+ /** Auth's `attestation` block, as `auth()` takes it. Absent, attestation is not configured. */
250
+ attestation?: z.input<typeof AttestationConfig>;
251
+ /** The root an App Attest key's chain must lead to, DER, in place of Apple's: a test device's. */
252
+ appAttestRoot?: Uint8Array;
253
+ /**
254
+ * Play Integrity's service account, stored as auth's secret, and the `fetch` the verifier calls Google with: a
255
+ * stand-in for Google's token endpoint and `decodeIntegrityToken`, so Google is the one thing not live.
256
+ */
257
+ playIntegrity?: {
258
+ account: PlayIntegrityServiceAccount;
259
+ fetch: typeof fetch;
260
+ } | undefined;
221
261
  }
222
262
  /** A booted app: where it listens, what it was pinned to, and what it recorded. */
223
263
  export interface LiveApp {
@@ -1 +1 @@
1
- {"version":3,"file":"liveApp.d.ts","sourceRoot":"","sources":["../../src/test-utils/liveApp.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,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;AA0BD,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;;;OAGG;IACH,EAAE,EAAE,UAAU,CAAC;IACf,yFAAyF;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CA4F5E"}
1
+ {"version":3,"file":"liveApp.d.ts","sourceRoot":"","sources":["../../src/test-utils/liveApp.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAc3E,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQ/D,OAAO,EAAuB,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAI5F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iHAAiH;AACjH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0D,CAAC;AAErF,4GAA4G;AAC5G,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA4BD,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;IACrB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;IAChD,kGAAkG;IAClG,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B;;;OAGG;IACH,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,2BAA2B,CAAC;QAAC,KAAK,EAAE,OAAO,KAAK,CAAA;KAAE,GAAG,SAAS,CAAC;CAC3F;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;;;OAGG;IACH,EAAE,EAAE,UAAU,CAAC;IACf,yFAAyF;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAuG5E"}
@@ -1,7 +1,9 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { publishSameOrigin } from "../http/csrf.js";
4
3
  import { authSecretsRegistry } from "../instance/secrets.js";
4
+ import { createPlayIntegrityVerifier } from "../attestation/playIntegrity/verifier.js";
5
+ import { PLATFORM_VERIFIERS } from "../attestation/verifier.js";
6
+ import { publishSameOrigin } from "../http/csrf.js";
5
7
  import { createSessionMiddleware } from "../http/middleware.js";
6
8
  import { createRateLimitMiddleware } from "../http/rateLimit.js";
7
9
  import { createAuthRoutes } from "../http/routes.js";
@@ -22,7 +24,7 @@ import { Hono } from "hono";
22
24
  import { Miniflare, convertV4MiniflareOptions } from "miniflare";
23
25
  //#region src/test-utils/liveApp.ts
24
26
  /**
25
- * A real auth Worker on a real port, for the live suites (#84).
27
+ * A real auth Worker on a real port, for the live suites.
26
28
  *
27
29
  * The live E2E questions this package has are about an **origin**: which `redirect_uri` Better Auth
28
30
  * hands Google, whether a token posted from a browser survives the humanity gate, whether a callback
@@ -36,7 +38,7 @@ import { Miniflare, convertV4MiniflareOptions } from "miniflare";
36
38
  *
37
39
  * - **Miniflare supplies D1**, from Node rather than from inside a worker. Two databases, as a deployed
38
40
  * worker has: `DB` for the `pithy_auth_*` and `pithy_email_*` tables, `SECRETS` for the encrypted
39
- * rows every secret is read from (#153). No plaintext binding stands in for either.
41
+ * rows every secret is read from. No plaintext binding stands in for either.
40
42
  * - **The migrations are the real ones**, run through the real registry and runner.
41
43
  * - **`node:http` gives the port.** Vitest's `fetch` reaches the app the way a browser would, so an
42
44
  * `Origin` header is a real one and a `Set-Cookie` is a real one.
@@ -56,6 +58,8 @@ function resetLiveSecrets() {
56
58
  /** Tables the app database holds once both capabilities' migrations have run. */
57
59
  const TABLES = [
58
60
  "pithy_auth_accounts",
61
+ "pithy_auth_app_attest_keys",
62
+ "pithy_auth_attestation_challenges",
59
63
  "pithy_auth_devices",
60
64
  "pithy_auth_jwks",
61
65
  "pithy_auth_rate_limit",
@@ -101,6 +105,7 @@ async function startLiveApp(options) {
101
105
  await migrate(db);
102
106
  const fixture = { "auth-session-secret": SESSION_SECRET };
103
107
  if (options.google) fixture["auth-google-credentials"] = options.google;
108
+ if (options.playIntegrity) fixture["auth-play-integrity-service-account"] = options.playIntegrity.account;
104
109
  if (options.turnstile) fixture["turnstile-secret-keys"] = { [options.turnstile.mode]: { key: options.turnstile.secretKey } };
105
110
  configureSharedSecrets({ registry: LIVE_REGISTRY });
106
111
  await seedSecrets(env, LIVE_REGISTRY, fixture);
@@ -117,14 +122,20 @@ async function startLiveApp(options) {
117
122
  baseURL: origin,
118
123
  basePath: options.basePath,
119
124
  trustedOrigins: [origin],
120
- google: { enabled: Boolean(options.google) }
125
+ google: { enabled: Boolean(options.google) },
126
+ ...options.attestation ? { attestation: options.attestation } : {}
121
127
  }),
122
128
  resolveGithubUserInfo: void 0,
123
129
  enqueueEmail: emailCapability.enqueue,
124
130
  turnstile: options.turnstile ? {
125
131
  mode: options.turnstile.mode,
126
132
  token: { field: "cf-turnstile-response" }
127
- } : void 0
133
+ } : void 0,
134
+ appAttestRoot: options.appAttestRoot,
135
+ ...options.playIntegrity ? { attestationVerifiers: {
136
+ ...PLATFORM_VERIFIERS,
137
+ android: createPlayIntegrityVerifier({ fetch: options.playIntegrity.fetch })
138
+ } } : {}
128
139
  }, events);
129
140
  server.on("request", (request, response) => {
130
141
  serve(app, env, origin, request, response);
@@ -0,0 +1,11 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { D1Database } from "@cloudflare/workers-types";
4
+ import type { MigrationProvider } from "kysely/migration";
5
+ import type { AUTH_MIGRATIONS } from "../migrations/set";
6
+ /**
7
+ * Roll the auth chain back until `key` is no longer applied, so a migration's own `down` is reached however many
8
+ * migrations were appended after it. Throws when `key` was never applied.
9
+ */
10
+ export declare function rollbackThrough(d1: D1Database, provider: MigrationProvider, key: keyof typeof AUTH_MIGRATIONS): Promise<void>;
11
+ //# sourceMappingURL=rollbackThrough.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rollbackThrough.d.ts","sourceRoot":"","sources":["../../src/test-utils/rollbackThrough.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,MAAM,OAAO,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf"}
@@ -0,0 +1,16 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { rollbackMigration } from "@pithy-sh/core/src/migrations/runner";
4
+ import { MIGRATION_TABLE } from "@pithy-sh/core/src/migrations/bookkeeping";
5
+ //#region src/test-utils/rollbackThrough.ts
6
+ /**
7
+ * Roll the auth chain back until `key` is no longer applied, so a migration's own `down` is reached however many
8
+ * migrations were appended after it. Throws when `key` was never applied.
9
+ */
10
+ async function rollbackThrough(d1, provider, key) {
11
+ const applied = async () => await d1.prepare(`select name from ${MIGRATION_TABLE} where name like ? limit 1`).bind(`%auth_${key}`).first() !== null;
12
+ if (!await applied()) throw new Error(`auth migration ${key} is not applied`);
13
+ while (await applied()) await rollbackMigration(d1, provider);
14
+ }
15
+ //#endregion
16
+ export { rollbackThrough };
@@ -146,6 +146,31 @@ export declare const SCOPED_REGISTRY: {
146
146
  readonly documentation: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade";
147
147
  };
148
148
  };
149
+ "auth-play-integrity-service-account": {
150
+ readonly backend: "d1";
151
+ readonly scope: "environment";
152
+ readonly rotatable: false;
153
+ readonly valueType: "json";
154
+ readonly schema: import("zod").ZodObject<{
155
+ type: import("zod").ZodOptional<import("zod").ZodLiteral<"service_account">>;
156
+ project_id: import("zod").ZodOptional<import("zod").ZodString>;
157
+ private_key_id: import("zod").ZodOptional<import("zod").ZodString>;
158
+ private_key: import("zod").ZodString;
159
+ client_email: import("zod").ZodString;
160
+ client_id: import("zod").ZodOptional<import("zod").ZodString>;
161
+ token_uri: import("zod").ZodOptional<import("zod").ZodString>;
162
+ }, import("zod/v4/core").$strip>;
163
+ readonly origin: {
164
+ readonly kind: "obtained";
165
+ readonly issuer: "google";
166
+ readonly documentation: "https://console.cloud.google.com/iam-admin/serviceaccounts";
167
+ };
168
+ readonly rotation: {
169
+ readonly kind: "manual";
170
+ readonly issuer: "google";
171
+ readonly documentation: "https://console.cloud.google.com/iam-admin/serviceaccounts";
172
+ };
173
+ };
149
174
  "email-link-signing-key": {
150
175
  readonly backend: "cf-secrets-store";
151
176
  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;AASlD;;;;;;;;;;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;;;;;;;GAOG;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,CAUf;AAkCD;;;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;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,UAAU,EACd,OAAO,SAAoB,GAC1B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAmC5D"}
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;AASlD;;;;;;;;;;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;;;;;;;GAOG;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,CAUf;AAkCD;;;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;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,UAAU,EACd,OAAO,SAAoB,GAC1B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAmC5D"}
@@ -1,7 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { authDatabase } from "../data/tables.js";
4
3
  import { authSecretsRegistry } from "../instance/secrets.js";
4
+ import { authDatabase } from "../data/tables.js";
5
5
  import { NO_SOCIAL_PROVIDERS } from "../instance/providers.js";
6
6
  import { makeAuth } from "../instance/auth.js";
7
7
  import "../migrations/0001_init.js";
@@ -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.15.3";
6
+ export declare const PACKAGE_VERSION = "0.17.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -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.15.3";
7
+ const PACKAGE_VERSION = "0.17.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -93,9 +93,9 @@ POST /auth/admin/users/:userId/export { reason }
93
93
 
94
94
  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.
95
95
 
96
- **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.
96
+ **Restore** clears both columns inside the window, records it, and fires [`onUserRestored`](#hooks). 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.
97
97
 
98
- **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 runs them. Each entry says what a purge does with its rows — `disposition` is `erase` or `retain`, and a `retain` entry carries the `basis` it is kept on, in the sentence written for the person — and then what it answered: `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. Every kit capability that holds rows about a person exports them, so `not_exported` is only ever an adopter's own capability; [what each one does](#what-each-capability-does-with-a-persons-rows) is below. Auth's own part is `AuthUserExport`: the account, its sessions, linked providers, devices, history, the sign-in links and codes the verification ledger records for it, 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. No kit capability's part carries one either: no opt-in token, no share link, no invitation digest, no provider payload, no Google Play purchase token, no message variables. 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.
98
+ **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 runs them. Each entry says what a purge does with its rows — `disposition` is `erase` or `retain`, and a `retain` entry carries the `basis` it is kept on, in the sentence written for the person and in their stored locale where the contribution names a `basisKey` a catalog translates ([`docs/I18N.md`](../../../docs/I18N.md#a-purges-retained-basis-reads-in-the-persons-language)), with that `basisKey` beside it — and then what it answered: `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. Every kit capability that holds rows about a person exports them, so `not_exported` is only ever an adopter's own capability; [what each one does](#what-each-capability-does-with-a-persons-rows) is below. Auth's own part is `AuthUserExport`: the account, its sessions, linked providers, devices, history, the sign-in links and codes the verification ledger records for it, 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. No kit capability's part carries one either: no opt-in token, no share link, no invitation digest, no provider payload, no Google Play purchase token, no message variables. 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.
99
99
 
100
100
  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`.
101
101
 
@@ -115,7 +115,7 @@ It is always soft, on the configured window, and the subject is always the sessi
115
115
 
116
116
  ## The purge
117
117
 
118
- 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. A contribution that **retains** its rows is a step too, and erases nothing: it records `purge_retained`, with the basis it gave as the reason, so the history never reads a kept step as an erased one. The order:
118
+ 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. A contribution that **retains** its rows is a step too, and erases nothing: it records `purge_retained`, with the basis it gave as the reason and its `basisKey` in `basis_key`, so the history never reads a kept step as an erased one. The order:
119
119
 
120
120
  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.
121
121
  2. Every composed contribution but auth's, in composition order, your `app` last. Each reads the account's address, when it needs one, inside its own step.
@@ -189,22 +189,58 @@ Four templates in `@pithy-sh/email`, all transactional, so an unsubscribe never
189
189
  ```ts
190
190
  auth({
191
191
  baseURL: "https://api.example.com",
192
- onUserSuspended: async (event, d1) => {},
193
- onUserReinstated: async (event, d1) => {},
194
- onUserDeleted: async (event, d1) => {},
195
- onUserPurged: async (event, d1) => {},
192
+ onUserSuspended: async (event, d1, runtime) => {},
193
+ onUserReinstated: async (event, d1, runtime) => {},
194
+ onUserDeleted: async (event, d1, runtime) => {},
195
+ onUserRestored: async (event, d1, runtime) => {},
196
+ onUserPurged: async (event, d1, runtime) => {},
196
197
  });
197
198
  ```
198
199
 
199
200
  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.
200
201
 
202
+ `onUserRestored` fires when a deleted account is restored inside its window, with the operator, the reason and `at`, the same event the other hooks get. Restoring an account that is not deleted fires nothing, and neither does a restore refused because the window closed. It is where you undo what `onUserDeleted` did:
203
+
204
+ ```ts
205
+ auth({
206
+ baseURL: "https://api.example.com",
207
+ onUserDeleted: async ({ userId, at }, d1) => {
208
+ await d1.prepare("update members set removed_at = ? where user_id = ?").bind(at.getTime(), userId).run();
209
+ },
210
+ onUserRestored: async ({ userId }, d1) => {
211
+ await d1.prepare("update members set removed_at = null where user_id = ?").bind(userId).run();
212
+ },
213
+ });
214
+ ```
215
+
216
+ Each hook is handed the event, the D1 binding, and `runtime`: `{ env, waitUntil? }`. `env` is the Worker's environment, so a hook can read a secret, start a Workflow, send to a queue, or call out. Pass your own `Env` to `auth<Env>()` and `runtime.env` is typed as it, with no cast. `onSessionRevoked` is handed the same `runtime` as its third argument.
217
+
218
+ `waitUntil` is the request's `ExecutionContext.waitUntil`. It is there when the hook fires inside a request, and absent when it fires from the purge Workflow, which has no `ExecutionContext`. `onUserPurged` always fires from the Workflow, and so does `onUserDeleted` for an account the daily inactivity pass deletes. Check for it before you call it.
219
+
220
+ Outside work belongs in a Workflow. The hook only starts it, which suits the hook's contract: it cannot fail the transition, and the Workflow retries the call.
221
+
222
+ ```ts
223
+ interface Env {
224
+ REVOKE_LINKED_ITEMS: Workflow<{ userId: string }>;
225
+ }
226
+
227
+ auth<Env>({
228
+ baseURL: "https://api.example.com",
229
+ onUserDeleted: async ({ userId }, _d1, { env }) => {
230
+ await env.REVOKE_LINKED_ITEMS.create({ params: { userId } });
231
+ },
232
+ });
233
+ ```
234
+
235
+ A hook written as `(event, d1)` still compiles and runs unchanged.
236
+
201
237
  ## Screens
202
238
 
203
239
  Three screens ship with auth and are yours after `pithy ui add react`, or in React Native primitives after `pithy ui add react-native`: 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.
204
240
 
205
241
  ## What each capability does with a person's rows
206
242
 
207
- Every kit capability that holds rows about a person declares a `user` contribution, and every one exports what it holds. Most erase. Four keep their rows, because the law or the record needs them, and say why.
243
+ Every kit capability that holds rows about a person declares a `user` contribution, and every one exports what it holds. Most erase. Five keep their rows, because the law or the record needs them, and say why — each basis under its own `<capability>/purge.retained` key, in English and Spanish, so the export reads it in the person's language.
208
244
 
209
245
  | Capability | Disposition | What |
210
246
  |---|---|---|
@@ -253,13 +289,13 @@ defineCapability({ name: "app", requiredBindings: [], purge: [purge] });
253
289
 
254
290
  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.
255
291
 
256
- **Or keep the rows, and say why.** Not every row about a person should go: a payment record is commonly kept for tax law, a suppression has to outlive the person or the unsubscribe stops holding, and an audit trail is the record of who acted. A contribution with `retain` is the third disposition beside erase and anonymize. It takes a basis, one sentence written for the person, and an `export`, which it may not leave out — rows that are kept are rows an access request is answered with — and no `erase`. `defineCapability` refuses one without a basis, without an export, or with an erase as well. The purge records the step as `purge_retained` and erases nothing; the export carries the rows, `disposition: "retain"` and the basis.
292
+ **Or keep the rows, and say why.** Not every row about a person should go: a payment record is commonly kept for tax law, a suppression has to outlive the person or the unsubscribe stops holding, and an audit trail is the record of who acted. A contribution with `retain` is the third disposition beside erase and anonymize. It takes a basis, one sentence written for the person, optionally the `basisKey` that translates it, and an `export`, which it may not leave out — rows that are kept are rows an access request is answered with — and no `erase`. `defineCapability` refuses one without a basis, with a `basisKey` outside its own domain, without an export, or with an erase as well. The purge records the step as `purge_retained`, with the basis and its key, and erases nothing; the export carries the rows, `disposition: "retain"`, the basis read in the person's locale, and the key. The basis stays required: it is the English every reader gets when nothing translates the key.
257
293
 
258
294
  ```ts
259
295
  const kept: PurgeContribution = {
260
296
  subject: "user",
261
297
  summary: "Keeps the user's invoices.",
262
- retain: { basis: "Kept for tax records." },
298
+ retain: { basis: "Kept for tax records.", basisKey: "app/purge.invoices_kept" },
263
299
  export: async ({ subject, env }) => ({ invoices: [] }),
264
300
  };
265
301
  ```