@pithy-sh/auth 0.15.2 → 0.16.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 (169) 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 +40 -0
  63. package/dist/capability.d.ts.map +1 -1
  64. package/dist/capability.js +38 -5
  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 +18 -1
  80. package/dist/data/tables.d.ts.map +1 -1
  81. package/dist/data/tables.js +6 -2
  82. package/dist/http/devLoginRoute.js +3 -3
  83. package/dist/http/resolve.js +1 -1
  84. package/dist/http/responses.d.ts +12 -0
  85. package/dist/http/responses.d.ts.map +1 -1
  86. package/dist/http/responses.js +11 -1
  87. package/dist/http/routes.d.ts +5 -1
  88. package/dist/http/routes.d.ts.map +1 -1
  89. package/dist/http/routes.js +92 -25
  90. package/dist/http/schemas.d.ts +7 -0
  91. package/dist/http/schemas.d.ts.map +1 -1
  92. package/dist/http/schemas.js +7 -1
  93. package/dist/index.js +1 -1
  94. package/dist/instance/secrets.d.ts +86 -7
  95. package/dist/instance/secrets.d.ts.map +1 -1
  96. package/dist/instance/secrets.js +54 -8
  97. package/dist/migrations/0009_attestation_challenges.d.ts +9 -0
  98. package/dist/migrations/0009_attestation_challenges.d.ts.map +1 -0
  99. package/dist/migrations/0009_attestation_challenges.js +21 -0
  100. package/dist/migrations/0010_app_attest_keys.d.ts +9 -0
  101. package/dist/migrations/0010_app_attest_keys.d.ts.map +1 -0
  102. package/dist/migrations/0010_app_attest_keys.js +17 -0
  103. package/dist/migrations/set.d.ts +3 -1
  104. package/dist/migrations/set.d.ts.map +1 -1
  105. package/dist/migrations/set.js +6 -2
  106. package/dist/seeds/devSession.js +1 -1
  107. package/dist/test-utils/appAttestDevice.d.ts +92 -0
  108. package/dist/test-utils/appAttestDevice.d.ts.map +1 -0
  109. package/dist/test-utils/appAttestDevice.js +282 -0
  110. package/dist/test-utils/appAttestSample.d.ts +22 -0
  111. package/dist/test-utils/appAttestSample.d.ts.map +1 -0
  112. package/dist/test-utils/appAttestSample.js +24 -0
  113. package/dist/test-utils/googlePlay.d.ts +47 -0
  114. package/dist/test-utils/googlePlay.d.ts.map +1 -0
  115. package/dist/test-utils/googlePlay.js +117 -0
  116. package/dist/test-utils/liveApp.d.ts +76 -36
  117. package/dist/test-utils/liveApp.d.ts.map +1 -1
  118. package/dist/test-utils/liveApp.js +16 -5
  119. package/dist/test-utils/rollbackThrough.d.ts +11 -0
  120. package/dist/test-utils/rollbackThrough.d.ts.map +1 -0
  121. package/dist/test-utils/rollbackThrough.js +16 -0
  122. package/dist/test-utils/scopedBackend.d.ts +25 -0
  123. package/dist/test-utils/scopedBackend.d.ts.map +1 -1
  124. package/dist/test-utils/scopedBackend.js +1 -1
  125. package/dist/version.generated.d.ts +1 -1
  126. package/dist/version.generated.js +1 -1
  127. package/docs/attestation.md +173 -0
  128. package/package.json +5 -5
  129. package/pithy.manifest.json +14 -0
  130. package/src/attestation/appAttest/assertion.ts +65 -0
  131. package/src/attestation/appAttest/attestation.ts +159 -0
  132. package/src/attestation/appAttest/authData.ts +45 -0
  133. package/src/attestation/appAttest/base64.ts +29 -0
  134. package/src/attestation/appAttest/bytes.ts +18 -0
  135. package/src/attestation/appAttest/cbor.ts +116 -0
  136. package/src/attestation/appAttest/der.ts +126 -0
  137. package/src/attestation/appAttest/keys.ts +57 -0
  138. package/src/attestation/appAttest/root.ts +13 -0
  139. package/src/attestation/appAttest/verifier.ts +113 -0
  140. package/src/attestation/appAttest/x509.ts +209 -0
  141. package/src/attestation/challenge.ts +56 -0
  142. package/src/attestation/config.ts +118 -0
  143. package/src/attestation/errors.ts +60 -0
  144. package/src/attestation/gate.ts +105 -0
  145. package/src/attestation/playIntegrity/google.ts +239 -0
  146. package/src/attestation/playIntegrity/verdict.ts +149 -0
  147. package/src/attestation/playIntegrity/verifier.ts +77 -0
  148. package/src/attestation/verifier.ts +87 -0
  149. package/src/attestation/wire.ts +79 -0
  150. package/src/capability.ts +64 -8
  151. package/src/client/api.ts +73 -40
  152. package/src/client/attestation.ts +404 -0
  153. package/src/client/projection.ts +29 -4
  154. package/src/data/appAttestKey.ts +45 -0
  155. package/src/data/attestationChallenge.ts +23 -0
  156. package/src/data/tables.ts +5 -1
  157. package/src/http/responses.ts +22 -0
  158. package/src/http/routes.ts +128 -38
  159. package/src/http/schemas.ts +24 -0
  160. package/src/instance/secrets.ts +88 -9
  161. package/src/migrations/0009_attestation_challenges.ts +28 -0
  162. package/src/migrations/0010_app_attest_keys.ts +27 -0
  163. package/src/migrations/set.ts +5 -1
  164. package/src/test-utils/appAttestDevice.ts +399 -0
  165. package/src/test-utils/appAttestSample.ts +20 -0
  166. package/src/test-utils/googlePlay.ts +144 -0
  167. package/src/test-utils/liveApp.ts +31 -5
  168. package/src/test-utils/rollbackThrough.ts +24 -0
  169. package/src/version.generated.ts +1 -1
@@ -5,13 +5,9 @@
5
5
  * same-origin, cookie-bearing request to this Worker, and the calls made through it — the six a
6
6
  * scaffolded screen makes, and {@link updateUser}, which an adopter's own screen calls.
7
7
  *
8
- * **This module lives in the package for the reason `@pithy-sh/payments`'s counterpart does, only more
9
- * so.** `pithy ui add` writes the auth screens once and may never rewrite them: they are copied into
10
- * the adopter's repository and become the adopter's files. Every request written into one of those
11
- * files is frozen there at the moment `pithy init` ran, and a later fix to the base path, the cookie
12
- * mode or the failure directions reaches none of them. Six such requests existed — `/get-session`,
13
- * `/sign-out`, the two OTP routes, the magic link, and the social handoff — each spelling out the same
14
- * transport by hand. They call this now, and this upgrades with a minor release (#370).
8
+ * **It lives in the package because the screens do not.** `pithy ui add` copies the auth screens into the
9
+ * adopter's repository once, and a request written out in one of them could never be fixed by a release. The
10
+ * screens call this, and this upgrades with a minor release.
15
11
  *
16
12
  * **Two transports, chosen by one option.** With no `origin`, every request is a rooted path on the
17
13
  * page's own origin carrying `credentials: "include"` and nothing else: no token in `localStorage` or
@@ -96,6 +92,21 @@ export type AuthGate = (body: Record<string, unknown>) => {
96
92
  /** The headers to send, with whatever header the check wanted added. */
97
93
  headers: Record<string, string>;
98
94
  };
95
+ /**
96
+ * A native app's attestation, for the two send routes: the headers that carry one over exactly `body`.
97
+ *
98
+ * `./attestation` builds it from a challenge and the platform's assertion. When a call carries one, the send is
99
+ * judged by it alone and the humanity check is not applied.
100
+ */
101
+ export interface AuthAttestation {
102
+ /** The headers to send with `body`, or the failure that stopped the attestation. */
103
+ attest(body: string): Promise<AuthResult<Record<string, string>>>;
104
+ /**
105
+ * The Worker refused the attestation in `headers`, the very object {@link AuthAttestation.attest} answered for the
106
+ * refused send, with `auth/attestation_failed`, so a key it named is not used again.
107
+ */
108
+ refused?(failure: AuthFailure, headers: Readonly<Record<string, string>>): void | Promise<void>;
109
+ }
99
110
  /** What every call takes: where the routes are, and the seams a test replaces. */
100
111
  export interface AuthClientOptions {
101
112
  /**
@@ -113,6 +124,8 @@ export interface AuthClientOptions {
113
124
  global?: AuthGlobal;
114
125
  /** The humanity check to satisfy, on the two routes that are gated by one. */
115
126
  gate?: AuthGate;
127
+ /** A native app's attestation, sent on those two routes in place of the humanity check. */
128
+ attestation?: AuthAttestation;
116
129
  }
117
130
  /** A refusal a screen can render: the namespaced code, the public message, and what to do next. */
118
131
  export interface AuthFailure {
@@ -143,6 +156,13 @@ export declare const AUTH_UNREADABLE: AuthFailure;
143
156
  * origin. Sending it would attach a session to a request this program is not entitled to make.
144
157
  */
145
158
  export declare const AUTH_CROSS_ORIGIN: AuthFailure;
159
+ /**
160
+ * Whether a refusal is the send gate's: Turnstile's `turnstile/*` or attestation's `auth/attestation_*`.
161
+ *
162
+ * The gate refuses before the address is looked at, so a screen may name it without telling a registered address
163
+ * from another. Every other refusal of a send is answered the same way whatever the address.
164
+ */
165
+ export declare function isGateRefusal(failure: AuthFailure): boolean;
146
166
  /**
147
167
  * Whether a composed path stays on this origin.
148
168
  *
@@ -183,11 +203,8 @@ export declare function withoutCookies(init: AuthRequestInit | undefined): AuthR
183
203
  * renders. A body that will not parse is the generic failure rather than a crash — a corporate proxy's
184
204
  * HTML page reaches a browser far more often than anyone expects.
185
205
  *
186
- * **Exported, and that is the point of it.** `@pithy-sh/auth` shipped no browser primitive at all, so
187
- * six scaffolded screens each wrote the transport out by hand — and those screens are copied into an
188
- * adopter's repository, where Pithy can never fix them. Every browser program that asks this Worker an
189
- * auth question calls this, and `sameOrigin.test.ts` fails the build on any module that grows its own
190
- * (#370).
206
+ * **Exported, so no screen writes a transport of its own.** Every browser program that asks this Worker an
207
+ * auth question calls this, and `sameOrigin.test.ts` fails the build on any module that grows its own.
191
208
  *
192
209
  * **Zod-free, like everything on this side of the wire.** The answer is narrowed by the hand-written
193
210
  * `guard` a caller passes, never by a schema: this compiles into an adopter's browser bundle, and
@@ -220,12 +237,9 @@ export declare function getSession(options?: AuthClientOptions): Promise<AuthRes
220
237
  /**
221
238
  * End the session server-side.
222
239
  *
223
- * **The content type is not decoration, and the scaffolded screen was missing it.** The route refuses a
224
- * POST without `application/json` with a 415 — so every app scaffolded so far has been signing nobody
225
- * out. It went unnoticed because the screen ignored the answer and navigated to `/sign-in` regardless,
226
- * which looks exactly like a successful sign-out until the back button restores a live session.
227
- * `clientRoundTrip.test.ts` is what found it, and is what would find it again: a request written into a
228
- * file Pithy may never rewrite is a request nobody ever tested against the route it names (#370).
240
+ * **The content type is required.** The route refuses a POST without `application/json` with a 415, and a
241
+ * screen that ignores the answer and navigates on would look signed out while the session lives.
242
+ * `clientRoundTrip.test.ts` holds this call against the real route.
229
243
  *
230
244
  * The body is an empty object rather than nothing, because a declared JSON content type with no body is
231
245
  * the other half of the same 415.
@@ -269,7 +283,7 @@ export declare function signOut(options?: AuthClientOptions): Promise<AuthResult
269
283
  * function.** Standing up a second Better Auth client with `inferAdditionalFields` duplicates
270
284
  * configuration `@pithy-sh/auth` already owns. Reaching for {@link callAuth} instead means an adopter
271
285
  * spelling out the path, the content type and the guard themselves, one deep import below the surface
272
- * every other auth call in their app goes through — written into a file Pithy can never fix (#446).
286
+ * every other auth call in their app goes through, in a file a release can never fix.
273
287
  *
274
288
  * **The answer carries no user, whatever the route's own OpenAPI block advertises.** Better Auth's
275
289
  * `/update-user` ends `ctx.json({ status: true })`, so `value` is `{ status: true }` and
@@ -296,8 +310,8 @@ export declare function signInWithOtp(input: {
296
310
  /**
297
311
  * Mail a one-time code.
298
312
  *
299
- * Gated by the humanity check when one is composed — `options.gate` puts the token where the middleware
300
- * reads it, and a screen cannot forget to.
313
+ * Gated: `options.attestation` attests over the request, and otherwise `options.gate` puts the humanity check's
314
+ * token where the middleware reads it. A gate's refusal comes back with its code; see {@link isGateRefusal}.
301
315
  */
302
316
  export declare function sendOtp(input: {
303
317
  email: string;
@@ -341,10 +355,9 @@ export type SocialSignIn = {
341
355
  * refused callback to `${baseURL}${basePath}/error`, which in production redirects on to the adopter's
342
356
  * home route carrying a query string no template reads — so the user lands on a page that says nothing
343
357
  * about what just happened. Pass the sign-in screen's own path and the refusal returns to the control
344
- * that started it, as `?error=<code>`. That is the transport the whole GitHub rejection copy depends on
345
- * (pithy-sh/pithy#554); without it the sentence exists and is unreachable.
358
+ * that started it, as `?error=<code>`, which is how a provider's refusal copy reaches the screen.
346
359
  *
347
- * **The value has a shape, and the Worker refuses one that does not fit (#625).** An absolute URL on a
360
+ * **The value has a shape, and the Worker refuses one that does not fit.** An absolute URL on a
348
361
  * trusted origin, or a root-relative path — with **no fragment** and no `error`/`error_description`
349
362
  * parameter already on it. Better Auth appends `?error=<code>` to this string without parsing it, so a
350
363
  * `#` anywhere in it swallows the code the refusal screen is waiting for, and an `error` already there
@@ -1 +1 @@
1
- {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"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"}
@@ -6,13 +6,9 @@
6
6
  * same-origin, cookie-bearing request to this Worker, and the calls made through it — the six a
7
7
  * scaffolded screen makes, and {@link updateUser}, which an adopter's own screen calls.
8
8
  *
9
- * **This module lives in the package for the reason `@pithy-sh/payments`'s counterpart does, only more
10
- * so.** `pithy ui add` writes the auth screens once and may never rewrite them: they are copied into
11
- * the adopter's repository and become the adopter's files. Every request written into one of those
12
- * files is frozen there at the moment `pithy init` ran, and a later fix to the base path, the cookie
13
- * mode or the failure directions reaches none of them. Six such requests existed — `/get-session`,
14
- * `/sign-out`, the two OTP routes, the magic link, and the social handoff — each spelling out the same
15
- * transport by hand. They call this now, and this upgrades with a minor release (#370).
9
+ * **It lives in the package because the screens do not.** `pithy ui add` copies the auth screens into the
10
+ * adopter's repository once, and a request written out in one of them could never be fixed by a release. The
11
+ * screens call this, and this upgrades with a minor release.
16
12
  *
17
13
  * **Two transports, chosen by one option.** With no `origin`, every request is a rooted path on the
18
14
  * page's own origin carrying `credentials: "include"` and nothing else: no token in `localStorage` or
@@ -67,6 +63,15 @@ const AUTH_CROSS_ORIGIN = {
67
63
  message: "That request would have left this site, so it wasn't sent.",
68
64
  action: "Check the auth `basePath` in pithy.config.ts, which is a path on the worker and not a URL, and the client's `origin`, which is a scheme and host with no path."
69
65
  };
66
+ /**
67
+ * Whether a refusal is the send gate's: Turnstile's `turnstile/*` or attestation's `auth/attestation_*`.
68
+ *
69
+ * The gate refuses before the address is looked at, so a screen may name it without telling a registered address
70
+ * from another. Every other refusal of a send is answered the same way whatever the address.
71
+ */
72
+ function isGateRefusal(failure) {
73
+ return failure.code.startsWith("turnstile/") || failure.code.startsWith("auth/attestation_");
74
+ }
70
75
  /** Whether a value is a plain record — the first step of every guard below. */
71
76
  function isRecord(value) {
72
77
  return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -124,14 +129,10 @@ function withoutCookies(init) {
124
129
  * route Better Auth owns — the one-time code, the magic link, sign-out, `get-session`, the social
125
130
  * handoff, `update-user` — answers its own flat `{ message, code }`, because better-call renders an
126
131
  * endpoint's `APIError` into a Response inside `instance.handler` and nothing on our side of that ever
127
- * sees it (#449).
132
+ * sees it. Both are read, so a mistyped one-time code reads as a wrong code rather than as a broken app.
128
133
  *
129
- * Reading only the envelope meant every one of those refusals arrived as {@link AUTH_UNREADABLE}, so a
130
- * reader who mistyped their one-time code was told the app was broken rather than that the code was
131
- * wrong — in a screen `pithy ui add` copies into an adopter's repository, where it can never be fixed.
132
- *
133
- * **The flat shape is read rather than rewritten on the server, deliberately.** `packages/auth/README.md`
134
- * documents `createAuthClient` from `better-auth/client` as a first-class client surface (#271), and
134
+ * **The flat shape is read rather than rewritten on the server.** `packages/auth/README.md` documents
135
+ * `createAuthClient` from `better-auth/client` as a first-class client surface, and
135
136
  * `@better-fetch/fetch` builds its error as `{ ...parsedBody, status }` — so an adopter on that path
136
137
  * reads `error.code === "INVALID_OTP"` today. Re-homing the body into our envelope would make that
137
138
  * `undefined` for every one of them. The wire is Better Auth's contract; this side learns to read it.
@@ -167,11 +168,8 @@ function readFailure(body) {
167
168
  * renders. A body that will not parse is the generic failure rather than a crash — a corporate proxy's
168
169
  * HTML page reaches a browser far more often than anyone expects.
169
170
  *
170
- * **Exported, and that is the point of it.** `@pithy-sh/auth` shipped no browser primitive at all, so
171
- * six scaffolded screens each wrote the transport out by hand — and those screens are copied into an
172
- * adopter's repository, where Pithy can never fix them. Every browser program that asks this Worker an
173
- * auth question calls this, and `sameOrigin.test.ts` fails the build on any module that grows its own
174
- * (#370).
171
+ * **Exported, so no screen writes a transport of its own.** Every browser program that asks this Worker an
172
+ * auth question calls this, and `sameOrigin.test.ts` fails the build on any module that grows its own.
175
173
  *
176
174
  * **Zod-free, like everything on this side of the wire.** The answer is narrowed by the hand-written
177
175
  * `guard` a caller passes, never by a schema: this compiles into an adopter's browser bundle, and
@@ -226,12 +224,7 @@ async function callAuth(path, init, options, guard) {
226
224
  failure: AUTH_UNREADABLE
227
225
  };
228
226
  }
229
- /**
230
- * A JSON POST, with the humanity check's contribution already folded in.
231
- *
232
- * The gate is applied here rather than at each call site for the reason the cookie mode is: a screen
233
- * that forgets it sends an ungated request to a gated route and gets a 403 it cannot explain.
234
- */
227
+ /** A JSON POST, with the humanity check's contribution folded in, so no call site can forget it. */
235
228
  function jsonPost(body, options) {
236
229
  const gated = options?.gate ? options.gate(body) : {
237
230
  body,
@@ -247,6 +240,27 @@ function jsonPost(body, options) {
247
240
  };
248
241
  }
249
242
  /**
243
+ * A send to a gated route: attested when `options.attestation` is set, and otherwise through {@link jsonPost}'s
244
+ * humanity check. A refused attestation is reported back to it, so a key the Worker refused is not used again.
245
+ */
246
+ async function gatedSend(path, body, options) {
247
+ const attestation = options?.attestation;
248
+ if (!attestation) return callAuth(path, jsonPost(body, options), options, isObject);
249
+ const serialized = JSON.stringify(body);
250
+ const attested = await attestation.attest(serialized);
251
+ if (!attested.ok) return attested;
252
+ const result = await callAuth(path, {
253
+ method: "POST",
254
+ headers: {
255
+ "content-type": "application/json",
256
+ ...attested.value
257
+ },
258
+ body: serialized
259
+ }, options, isObject);
260
+ if (!result.ok && result.failure.code === "auth/attestation_failed") await attestation.refused?.(result.failure, attested.value);
261
+ return result;
262
+ }
263
+ /**
250
264
  * Whether a value is a session envelope, or the explicit "nobody" the route answers with.
251
265
  *
252
266
  * `null` is a valid answer and a distinct one from a failure — signed out is not the same as unread —
@@ -277,12 +291,9 @@ function getSession(options) {
277
291
  /**
278
292
  * End the session server-side.
279
293
  *
280
- * **The content type is not decoration, and the scaffolded screen was missing it.** The route refuses a
281
- * POST without `application/json` with a 415 — so every app scaffolded so far has been signing nobody
282
- * out. It went unnoticed because the screen ignored the answer and navigated to `/sign-in` regardless,
283
- * which looks exactly like a successful sign-out until the back button restores a live session.
284
- * `clientRoundTrip.test.ts` is what found it, and is what would find it again: a request written into a
285
- * file Pithy may never rewrite is a request nobody ever tested against the route it names (#370).
294
+ * **The content type is required.** The route refuses a POST without `application/json` with a 415, and a
295
+ * screen that ignores the answer and navigates on would look signed out while the session lives.
296
+ * `clientRoundTrip.test.ts` holds this call against the real route.
286
297
  *
287
298
  * The body is an empty object rather than nothing, because a declared JSON content type with no body is
288
299
  * the other half of the same 415.
@@ -332,7 +343,7 @@ function signOut(options) {
332
343
  * function.** Standing up a second Better Auth client with `inferAdditionalFields` duplicates
333
344
  * configuration `@pithy-sh/auth` already owns. Reaching for {@link callAuth} instead means an adopter
334
345
  * spelling out the path, the content type and the guard themselves, one deep import below the surface
335
- * every other auth call in their app goes through — written into a file Pithy can never fix (#446).
346
+ * every other auth call in their app goes through, in a file a release can never fix.
336
347
  *
337
348
  * **The answer carries no user, whatever the route's own OpenAPI block advertises.** Better Auth's
338
349
  * `/update-user` ends `ctx.json({ status: true })`, so `value` is `{ status: true }` and
@@ -362,11 +373,11 @@ function signInWithOtp(input, options) {
362
373
  /**
363
374
  * Mail a one-time code.
364
375
  *
365
- * Gated by the humanity check when one is composed — `options.gate` puts the token where the middleware
366
- * reads it, and a screen cannot forget to.
376
+ * Gated: `options.attestation` attests over the request, and otherwise `options.gate` puts the humanity check's
377
+ * token where the middleware reads it. A gate's refusal comes back with its code; see {@link isGateRefusal}.
367
378
  */
368
379
  function sendOtp(input, options) {
369
- return callAuth("/email-otp/send-verification-otp", jsonPost({ ...input }, options), options, isObject);
380
+ return gatedSend("/email-otp/send-verification-otp", { ...input }, options);
370
381
  }
371
382
  /**
372
383
  * Mail a magic link.
@@ -375,7 +386,7 @@ function sendOtp(input, options) {
375
386
  * {@link sendOtp}.
376
387
  */
377
388
  function sendMagicLink(input, options) {
378
- return callAuth("/sign-in/magic-link", jsonPost({ ...input }, options), options, isObject);
389
+ return gatedSend("/sign-in/magic-link", { ...input }, options);
379
390
  }
380
391
  /**
381
392
  * Whether an answer is an authorization URL a browser may be sent to, and the two reasons it might not be.
@@ -411,10 +422,9 @@ function isAuthorization(value) {
411
422
  * refused callback to `${baseURL}${basePath}/error`, which in production redirects on to the adopter's
412
423
  * home route carrying a query string no template reads — so the user lands on a page that says nothing
413
424
  * about what just happened. Pass the sign-in screen's own path and the refusal returns to the control
414
- * that started it, as `?error=<code>`. That is the transport the whole GitHub rejection copy depends on
415
- * (pithy-sh/pithy#554); without it the sentence exists and is unreachable.
425
+ * that started it, as `?error=<code>`, which is how a provider's refusal copy reaches the screen.
416
426
  *
417
- * **The value has a shape, and the Worker refuses one that does not fit (#625).** An absolute URL on a
427
+ * **The value has a shape, and the Worker refuses one that does not fit.** An absolute URL on a
418
428
  * trusted origin, or a root-relative path — with **no fragment** and no `error`/`error_description`
419
429
  * parameter already on it. Better Auth appends `?error=<code>` to this string without parsing it, so a
420
430
  * `#` anywhere in it swallows the code the refusal screen is waiting for, and an `error` already there
@@ -425,7 +435,8 @@ function isAuthorization(value) {
425
435
  async function startSocialSignIn(input, options) {
426
436
  const ungated = options && {
427
437
  ...options,
428
- gate: void 0
438
+ gate: void 0,
439
+ attestation: void 0
429
440
  };
430
441
  const result = await callAuth("/sign-in/social", jsonPost({ ...input }, void 0), ungated, isObject);
431
442
  if (!result.ok) return {
@@ -438,4 +449,4 @@ async function startSocialSignIn(input, options) {
438
449
  } : { kind: "unconfigured" };
439
450
  }
440
451
  //#endregion
441
- export { AUTH_BASE_PATH, AUTH_CROSS_ORIGIN, AUTH_UNREACHABLE, AUTH_UNREADABLE, callAuth, getSession, isBareOrigin, isSameOriginPath, resolveFetch, sendMagicLink, sendOtp, signInWithOtp, signOut, startSocialSignIn, updateUser, withoutCookies };
452
+ export { AUTH_BASE_PATH, AUTH_CROSS_ORIGIN, AUTH_UNREACHABLE, AUTH_UNREADABLE, callAuth, getSession, isBareOrigin, isGateRefusal, isSameOriginPath, resolveFetch, sendMagicLink, sendOtp, signInWithOtp, signOut, startSocialSignIn, updateUser, withoutCookies };
@@ -0,0 +1,148 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { type AuthAttestation, type AuthClientOptions, type AuthFailure, type AuthResult } from "./api";
4
+ import type { SecureStore } from "./bearer";
5
+ /**
6
+ * A native app's attestation on the two send routes: a challenge from the Worker, the platform's assertion over
7
+ * that challenge and the send's exact body, and the one header that carries both.
8
+ *
9
+ * **The platform is an injected adapter.** {@link appAttestAttester} and {@link playIntegrityAttester} take
10
+ * `@expo/app-integrity`'s functions as a structural argument, so this package never depends on it: the scaffolded
11
+ * React Native app installs it and hands it in, and a web-only or server-only project installs nothing for this.
12
+ * {@link testAttester} sends the documented test assertion, for simulators, emulators and CI.
13
+ *
14
+ * Nothing here throws. A platform that will not attest, and a Worker that will not issue a challenge, are each an
15
+ * {@link AuthFailure}.
16
+ */
17
+ /** The request header the attestation travels in. The Worker's own name for it is in `../attestation/wire`. */
18
+ export declare const ATTESTATION_HEADER = "x-pithy-attestation";
19
+ /** The assertion a `test` environment accepts in place of a real one. */
20
+ export declare const ATTESTATION_TEST_ASSERTION = "pithy-test-attestation";
21
+ /** Where an App Attest key id is kept between launches, by default. */
22
+ export declare const APP_ATTEST_KEY_STORAGE_KEY = "pithy.attestation.appAttestKey";
23
+ /** The platform would not attest: no App Attest on this device, Play services missing, or a key it refused. */
24
+ export declare const ATTESTATION_UNAVAILABLE: AuthFailure;
25
+ /** What an attester is asked to attest over. */
26
+ export interface AttestationRequest {
27
+ /** The challenge the Worker issued. */
28
+ readonly challenge: string;
29
+ /** The send's body, exactly as it goes on the wire. */
30
+ readonly body: string;
31
+ /** SHA-256 of the challenge's UTF-8 followed by the body's: what the Worker checks the assertion against. */
32
+ readonly binding: Uint8Array;
33
+ }
34
+ /** What an attester produced. */
35
+ export interface AttestationProof {
36
+ /** The App Attest assertion, the Play Integrity token, or the test assertion. */
37
+ readonly assertion: string;
38
+ /** The App Attest key id, on iOS. */
39
+ readonly keyId?: string;
40
+ }
41
+ /** What an attester may ask of the Worker besides the send it attests: the calls a key's registration makes. */
42
+ export interface AttestationTransport {
43
+ /** A fresh single-use challenge from `POST {basePath}/attestation/challenge`. */
44
+ challenge(): Promise<AuthResult<string>>;
45
+ /** Register an App Attest key with Apple's attestation of it, at `POST {basePath}/attestation/ios/keys`. */
46
+ registerAppAttestKey(input: {
47
+ challenge: string;
48
+ keyId: string;
49
+ attestation: string;
50
+ }): Promise<AuthResult<void>>;
51
+ }
52
+ /**
53
+ * The Worker refused a call an attester made through its {@link AttestationTransport}. Thrown by an attester and
54
+ * answered by the send as {@link AttestationRefusedError.failure}, so a refused registration reaches the screen with
55
+ * the Worker's code rather than as {@link ATTESTATION_UNAVAILABLE}.
56
+ */
57
+ export declare class AttestationRefusedError extends Error {
58
+ readonly failure: AuthFailure;
59
+ constructor(failure: AuthFailure);
60
+ }
61
+ /** One platform's attestation, injected. */
62
+ export interface Attester {
63
+ /** The platform the Worker judges the assertion as. */
64
+ readonly platform: "ios" | "android";
65
+ /** Whether this device can attest at all. Absent means it can. A screen offers Turnstile where it cannot. */
66
+ readonly available?: boolean;
67
+ /**
68
+ * The assertion over `request`. `transport` reaches the Worker for anything the assertion needs first, such as
69
+ * registering a key. May throw: the caller answers an {@link AttestationRefusedError} with its failure and any
70
+ * other throw with {@link ATTESTATION_UNAVAILABLE}.
71
+ */
72
+ attest(request: AttestationRequest, transport: AttestationTransport): Promise<AttestationProof>;
73
+ /**
74
+ * The Worker refused `proof`, which this produced for one send. An attester drops the key that proof used, and
75
+ * only that key, so the next send starts over without losing a newer key another send registered.
76
+ */
77
+ refused?(proof: AttestationProof): Promise<void>;
78
+ }
79
+ /** The test assertion from `platform`. A `test` environment accepts it; nothing else does. */
80
+ export declare function testAttester(platform: "ios" | "android"): Attester;
81
+ /** The App Attest half of `@expo/app-integrity`, as this module calls it. */
82
+ export interface AppAttestModule {
83
+ /** Whether this device provides App Attest. */
84
+ readonly isSupported: boolean;
85
+ /** A new key in the Secure Enclave, by its id. */
86
+ generateKeyAsync(): Promise<string>;
87
+ /** Apple's attestation of the key, over SHA-256 of `challenge`'s UTF-8. */
88
+ attestKeyAsync(keyId: string, challenge: string): Promise<string>;
89
+ /** An assertion by the key, over SHA-256 of `challenge`'s UTF-8. */
90
+ generateAssertionAsync(keyId: string, challenge: string): Promise<string>;
91
+ }
92
+ /**
93
+ * Apple App Attest.
94
+ *
95
+ * **A key is registered once, then asserts.** With no registered key, a send generates one, asks the Worker for a
96
+ * challenge, has Apple attest the key over it, and posts the attestation object to `/attestation/ios/keys`. The key
97
+ * is kept in `store`, the Keychain on a phone, only when that route answers success; a key it refused, or that never
98
+ * reached it, is never asserted with, and the next send registers another. Then that send, and every later one,
99
+ * asserts with the key over its own challenge and exact body.
100
+ *
101
+ * **A key that stops working is replaced.** A key the device can no longer assert with, which is what a Keychain
102
+ * entry outliving a reinstall or a restore leaves, is dropped and a new one registered on the same send, unless
103
+ * another send has registered one meanwhile, which this send then asserts with. A send the Worker refuses with
104
+ * `auth/attestation_failed` drops the key that send used, through {@link Attester.refused}, so the next send
105
+ * registers a new one; a refusal arriving after a newer key replaced it leaves the newer key alone.
106
+ *
107
+ * **Sends share their work.** The stored key id is read once per launch however many sends start together, and
108
+ * one registration at a time serves every send waiting on a key.
109
+ *
110
+ * **What the module is handed is what the Worker hashes.** `@expo/app-integrity` hashes the string it is handed into
111
+ * `clientDataHash`. Registration hands it the challenge alone, whose SHA-256 is the binding over the challenge and an
112
+ * empty body; an assertion hands it the challenge followed by the send's body, whose SHA-256 is the send's binding.
113
+ */
114
+ export declare function appAttestAttester(input: {
115
+ module: AppAttestModule;
116
+ store: SecureStore;
117
+ storageKey?: string;
118
+ }): Attester;
119
+ /** The Play Integrity half of `@expo/app-integrity`, as this module calls it. */
120
+ export interface PlayIntegrityModule {
121
+ /** Warm up the token provider for a Google Cloud project, by its number. */
122
+ prepareIntegrityTokenProviderAsync(cloudProjectNumber: string): Promise<void>;
123
+ /** A Play Integrity token bound to `requestHash`. */
124
+ requestIntegrityCheckAsync(requestHash: string): Promise<string>;
125
+ }
126
+ /**
127
+ * Google Play Integrity, standard requests. The provider is prepared for the Google Cloud project the app is linked
128
+ * to in Play Console, and prepared again after any failure, since the module does not prepare an invalid provider
129
+ * again by itself; each send asks for a token whose `requestHash` is the binding's base64url. With no project
130
+ * number there is nothing to prepare, and {@link Attester.available} is `false`.
131
+ */
132
+ export declare function playIntegrityAttester(input: {
133
+ module: PlayIntegrityModule;
134
+ cloudProjectNumber: string | null;
135
+ }): Attester;
136
+ /** Unpadded base64url, the encoding the attestation header and Play Integrity's `requestHash` take. */
137
+ export declare function base64Url(bytes: Uint8Array): string;
138
+ /**
139
+ * The attestation a gated send takes as `options.attestation`: one challenge per send, the attester's assertion
140
+ * over it and the body, and the header that carries them. `options` reaches the challenge route the way every
141
+ * other auth call does, so on a phone it is the bearer session's.
142
+ */
143
+ export declare function createAttestation(input: AuthClientOptions & {
144
+ attester: Attester;
145
+ /** SHA-256. Web Crypto's by default. */
146
+ digest?: (bytes: Uint8Array) => Promise<Uint8Array>;
147
+ }): AuthAttestation;
148
+ //# sourceMappingURL=attestation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../src/client/attestation.ts"],"names":[],"mappings":"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"}