tom/HealthLog
1
0 Fork 0
mirror of https://github.com/MBombeck/HealthLog.git synced 2026-11-09 13:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Publish the passkey list and the base-token 422

Browse Source 
GET /api/auth/passkeys was absent from the contract entirely — no path
entry, no schema — while the client teams had been pointed at a published
schema for it since v1.32.8. It is now registered with the shape the route
actually serves: id, name, credentialDeviceType, credentialBackedUp,
createdAt, and the nullable lastUsedAt that started this. The route itself
is unchanged; only the record of it was missing. PasskeyInfo is deliberately
separate from WebauthnMfaCredentialInfo — one lists sign-in credentials, the
other second-factor security keys, and merging them would blur two surfaces
that behave differently. The route test now compares the projection the
route asks Prisma for against the published property set, so neither end can
move without the other.

`invalid_base_updated_at` existed only in route tests. It is now on all
eight published endpoints that accept a `baseUpdatedAt` body token, and the
field description says the thing implementers keep getting wrong: an
unparseable token, `null` included, is rejected with 422 rather than falling
back to the unconditional write. Omitting the key is the only way to get
that write.

/api/auth/me/health-score-config also returns this 422 but is not in the
spec at all; publishing that route is a separate piece of work.
This commit is contained in:
Marc-André Bombeck committed 2026-08-01 11:49:40 +02:00
1 parent 43c591fe19
commit 6a69bad05e
9 files changed
+317 -83
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/api/openapi.yaml
+194 -81
View File
@@ -2196,6 +2196,24 @@ paths:
"401": *a1
"422": *a3
"429": *a4
/api/auth/passkeys:
get:
tags:
- Auth
summary: List the caller's registered passkeys
description: The passkeys registered for primary sign-in, newest first. Distinct from the second-factor security keys in
`GET /api/auth/2fa/status` (`webauthn`) — a passkey replaces the password, a security key is asserted after one.
`lastUsedAt` is stamped on every verified assertion and is null only for a passkey that has never signed in.
responses:
"200":
description: The caller's passkeys, newest first.
content:
application/json:
schema:
$ref: "#/components/schemas/PasskeyListEnvelope"
"401": *a1
"422": *a3
"429": *a4
/api/auth/me/sessions:
get:
tags:
@@ -3685,7 +3703,14 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": &a6
description: Request validation failed. When the body carried a `baseUpdatedAt` that could not be parsed as an ISO-8601
timestamp — including an explicit `null` — `meta.errorCode` = `invalid_base_updated_at` and nothing was
written. Omit the key entirely for the unconditional write; do not send `null` for it.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"429": *a4
delete:
tags:
@@ -4688,7 +4713,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
/api/auth/me/disable-coach:
get:
@@ -4821,7 +4846,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
/api/auth/me/source-priority:
get:
@@ -5847,7 +5872,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
/api/auth/me/report-selection:
get:
@@ -6291,7 +6316,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
delete:
tags:
@@ -6469,8 +6494,11 @@ paths:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the
stored row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat
as opaque: only ever echo a server-returned value, never parse or synthesise it."
stored row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note
that this is NOT the unconditional write: sending `null` or a malformed string is rejected rather
than treated as an omitted token. Treat as opaque: only ever echo a server-returned value, never
parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -6491,7 +6519,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
/api/anamnesis/facts:
get:
@@ -6616,7 +6644,7 @@ paths:
schema:
$ref: "#/components/schemas/CorrectAnamnesisFactResponse"
"401": *a1
"404": &a6
"404": &a7
description: No current revision with this id exists for the authenticated account.
content:
application/json:
@@ -6652,7 +6680,7 @@ paths:
schema:
$ref: "#/components/schemas/RemoveAnamnesisFactResponse"
"401": *a1
"404": *a6
"404": *a7
"409":
description: Anamnesis fact changed since it was loaded (optimistic-concurrency conflict). No write happened. Re-read
the resource, re-apply the user's change against the fresh state, and resend with the new token.
@@ -7783,9 +7811,11 @@ paths:
- in: query
name: type
schema:
description: For VITALS_BASELINE only — the single vital to band (defaults to RESTING_HEART_RATE). Ignored by
composites. An unsupported value yields an `insufficient` value rather than a 422 so iOS metric
combinations stay forgiving.
description: The single measurement type a baseline metric works over. `VITALS_BASELINE` takes one of the eleven vitals
(`RESTING_HEART_RATE` through `WEIGHT`; defaults to `RESTING_HEART_RATE`). `SAME_TIME_BASELINE` takes one
of the four cumulative day metrics — `ACTIVITY_STEPS`, `ACTIVE_ENERGY_BURNED`, `WALKING_RUNNING_DISTANCE`,
`FLIGHTS_CLIMBED`. Ignored by the composite metrics. A type the named metric does not support yields an
`insufficient` value rather than a 422, so client metric combinations stay forgiving.
type: string
enum:
- RESTING_HEART_RATE
@@ -7799,9 +7829,15 @@ paths:
- BLOOD_GLUCOSE
- PULSE
- WEIGHT
description: For VITALS_BASELINE only — the single vital to band (defaults to RESTING_HEART_RATE). Ignored by
composites. An unsupported value yields an `insufficient` value rather than a 422 so iOS metric combinations
stay forgiving.
- ACTIVITY_STEPS
- ACTIVE_ENERGY_BURNED
- WALKING_RUNNING_DISTANCE
- FLIGHTS_CLIMBED
description: The single measurement type a baseline metric works over. `VITALS_BASELINE` takes one of the eleven vitals
(`RESTING_HEART_RATE` through `WEIGHT`; defaults to `RESTING_HEART_RATE`). `SAME_TIME_BASELINE` takes one of
the four cumulative day metrics — `ACTIVITY_STEPS`, `ACTIVE_ENERGY_BURNED`, `WALKING_RUNNING_DISTANCE`,
`FLIGHTS_CLIMBED`. Ignored by the composite metrics. A type the named metric does not support yields an
`insufficient` value rather than a 422, so client metric combinations stay forgiving.
responses:
"200":
description: The flat derived-metric value (ok or insufficient).
@@ -7830,12 +7866,16 @@ paths:
minLength: 1
maxLength: 1024
description: Comma-separated derived-metric tokens. Each is a `<DERIVED_METRIC_ID>` or
`<DERIVED_METRIC_ID>:<MeasurementType>` (the colon sub-targets a VITALS_BASELINE vital). An unknown id
422s; a `type` outside the MeasurementType enum 422s; at most 24 tokens; duplicates collapse.
`<DERIVED_METRIC_ID>:<MeasurementType>` (the colon sub-targets the single measurement type a baseline
metric works over — a vital for `VITALS_BASELINE`, a cumulative day metric for `SAME_TIME_BASELINE`; see
the `type` parameter on `GET /api/insights/derived`). An unknown id 422s; a `type` outside the
MeasurementType enum 422s; at most 24 tokens; duplicates collapse.
required: true
description: Comma-separated derived-metric tokens. Each is a `<DERIVED_METRIC_ID>` or
`<DERIVED_METRIC_ID>:<MeasurementType>` (the colon sub-targets a VITALS_BASELINE vital). An unknown id 422s;
a `type` outside the MeasurementType enum 422s; at most 24 tokens; duplicates collapse.
`<DERIVED_METRIC_ID>:<MeasurementType>` (the colon sub-targets the single measurement type a baseline metric
works over — a vital for `VITALS_BASELINE`, a cumulative day metric for `SAME_TIME_BASELINE`; see the `type`
parameter on `GET /api/insights/derived`). An unknown id 422s; a `type` outside the MeasurementType enum
422s; at most 24 tokens; duplicates collapse.
responses:
"200":
description: The map of derived-metric values, keyed by token.
@@ -8222,7 +8262,7 @@ paths:
schema:
$ref: "#/components/schemas/MoodCustomTagPatchEnvelope"
"401": *a1
"404": &a7
"404": &a8
description: Not found / not owned by the caller.
content:
application/json:
@@ -8257,7 +8297,7 @@ paths:
schema:
$ref: "#/components/schemas/MoodCustomTagDeleteEnvelope"
"401": *a1
"404": *a7
"404": *a8
"422": *a3
"429": *a4
/api/mood/tags/{key}/hidden:
@@ -8298,7 +8338,7 @@ paths:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"401": *a1
"404": *a7
"404": *a8
"422": *a3
"429": *a4
/api/mood/tags/groups:
@@ -8373,7 +8413,7 @@ paths:
schema:
$ref: "#/components/schemas/MoodTagGroupPatchEnvelope"
"401": *a1
"404": *a7
"404": *a8
"422": *a3
"429": *a4
delete:
@@ -8404,7 +8444,7 @@ paths:
schema:
$ref: "#/components/schemas/MoodTagGroupDeleteEnvelope"
"401": *a1
"404": *a7
"404": *a8
"422": *a3
"429": *a4
/api/mood/tags/layout:
@@ -8452,7 +8492,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
/api/settings/reminder-thresholds:
get:
@@ -8648,7 +8688,7 @@ paths:
schema:
$ref: "#/components/schemas/MeasurementReminderEnvelope"
"401": *a1
"404": &a8
"404": &a9
description: Measurement reminder not found / not owned.
content:
application/json:
@@ -8682,7 +8722,7 @@ paths:
schema:
$ref: "#/components/schemas/MeasurementReminderPatchEnvelope"
"401": *a1
"404": *a8
"404": *a9
"422": *a3
"429": *a4
delete:
@@ -8704,7 +8744,7 @@ paths:
schema:
$ref: "#/components/schemas/MeasurementReminderDeleteEnvelope"
"401": *a1
"404": *a8
"404": *a9
"422": *a3
"429": *a4
/api/measurement-reminders/{id}/satisfy:
@@ -8728,7 +8768,7 @@ paths:
schema:
$ref: "#/components/schemas/MeasurementReminderSatisfyEnvelope"
"401": *a1
"404": *a8
"404": *a9
"422": *a3
"429": *a4
/api/measurement-reminders/{id}/complete:
@@ -8755,7 +8795,7 @@ paths:
schema:
$ref: "#/components/schemas/MeasurementReminderCompleteEnvelope"
"401": *a1
"404": *a8
"404": *a9
"422": *a3
"429": *a4
/api/labs:
@@ -8920,7 +8960,7 @@ paths:
schema:
$ref: "#/components/schemas/GetLabResultResponse"
"401": *a1
"404": &a9
"404": &a10
description: Lab result not found (or owned by another user).
content:
application/json:
@@ -8998,7 +9038,7 @@ paths:
schema:
$ref: "#/components/schemas/UpdateLabResultResponse"
"401": *a1
"404": *a9
"404": *a10
"422": *a3
"429": *a4
delete:
@@ -9020,7 +9060,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteLabResultResponse"
"401": *a1
"404": *a9
"404": *a10
"422": *a3
"429": *a4
/api/labs/restore:
@@ -9237,7 +9277,7 @@ paths:
schema:
$ref: "#/components/schemas/CreateBiomarkerResponse"
"401": *a1
"409": &a11
"409": &a12
description: A biomarker with this name already exists for the caller.
content:
application/json:
@@ -9265,7 +9305,7 @@ paths:
schema:
$ref: "#/components/schemas/GetBiomarkerResponse"
"401": *a1
"404": &a10
"404": &a11
description: Biomarker not found (or owned by another user).
content:
application/json:
@@ -9332,8 +9372,8 @@ paths:
schema:
$ref: "#/components/schemas/UpdateBiomarkerResponse"
"401": *a1
"404": *a10
"409": *a11
"404": *a11
"409": *a12
"422": *a3
"429": *a4
delete:
@@ -9356,7 +9396,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteBiomarkerResponse"
"401": *a1
"404": *a10
"404": *a11
"422": *a3
"429": *a4
/api/illness/episodes:
@@ -9481,7 +9521,7 @@ paths:
schema:
$ref: "#/components/schemas/GetIllnessEpisodeEnvelope"
"401": *a1
"404": &a12
"404": &a13
description: Illness episode not found (or owned by another user).
content:
application/json:
@@ -9559,7 +9599,7 @@ paths:
schema:
$ref: "#/components/schemas/UpdateIllnessEpisodeEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
delete:
@@ -9582,7 +9622,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteIllnessEpisodeEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
/api/illness/episodes/{id}/restore:
@@ -9608,7 +9648,7 @@ paths:
schema:
$ref: "#/components/schemas/RestoreIllnessEpisodeEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
/api/illness/episodes/{id}/resolve:
@@ -9644,7 +9684,7 @@ paths:
schema:
$ref: "#/components/schemas/ResolveIllnessEpisodeEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
/api/illness/episodes/{id}/day-logs:
@@ -9694,7 +9734,7 @@ paths:
schema:
$ref: "#/components/schemas/GetIllnessDayLogEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
post:
@@ -9773,7 +9813,7 @@ paths:
schema:
$ref: "#/components/schemas/UpsertIllnessDayLogCreatedEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
/api/illness/episodes/{id}/correlation:
@@ -9800,7 +9840,7 @@ paths:
schema:
$ref: "#/components/schemas/IllnessCorrelationEnvelope"
"401": *a1
"404": *a12
"404": *a13
"422": *a3
"429": *a4
/api/illness/insights:
@@ -10068,7 +10108,7 @@ paths:
schema:
$ref: "#/components/schemas/GetAllergyEnvelope"
"401": *a1
"404": &a13
"404": &a14
description: Allergy not found (or owned by another user).
content:
application/json:
@@ -10150,7 +10190,7 @@ paths:
schema:
$ref: "#/components/schemas/UpdateAllergyEnvelope"
"401": *a1
"404": *a13
"404": *a14
"422": *a3
"429": *a4
delete:
@@ -10173,7 +10213,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteAllergyEnvelope"
"401": *a1
"404": *a13
"404": *a14
"422": *a3
"429": *a4
/api/family-history:
@@ -10278,7 +10318,7 @@ paths:
schema:
$ref: "#/components/schemas/GetFamilyHistoryEnvelope"
"401": *a1
"404": &a14
"404": &a15
description: Family history entry not found (or owned by another user).
content:
application/json:
@@ -10346,7 +10386,7 @@ paths:
schema:
$ref: "#/components/schemas/UpdateFamilyHistoryEnvelope"
"401": *a1
"404": *a14
"404": *a15
"422": *a3
"429": *a4
delete:
@@ -10369,7 +10409,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteFamilyHistoryEnvelope"
"401": *a1
"404": *a14
"404": *a15
"422": *a3
"429": *a4
/api/documents/inbound:
@@ -11478,7 +11518,7 @@ paths:
schema:
$ref: "#/components/schemas/CreateCustomMetricResponse"
"401": *a1
"409": &a16
"409": &a17
description: A custom metric with this name already exists for the caller.
content:
application/json:
@@ -11506,7 +11546,7 @@ paths:
schema:
$ref: "#/components/schemas/GetCustomMetricResponse"
"401": *a1
"404": &a15
"404": &a16
description: Custom metric not found (or owned by another user).
content:
application/json:
@@ -11570,8 +11610,8 @@ paths:
schema:
$ref: "#/components/schemas/UpdateCustomMetricResponse"
"401": *a1
"404": *a15
"409": *a16
"404": *a16
"409": *a17
"422": *a3
"429": *a4
delete:
@@ -11594,7 +11634,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteCustomMetricResponse"
"401": *a1
"404": *a15
"404": *a16
"422": *a3
"429": *a4
/api/custom-metrics/{id}/entries:
@@ -11637,7 +11677,7 @@ paths:
schema:
$ref: "#/components/schemas/ListCustomMetricEntriesEnvelope"
"401": *a1
"404": *a15
"404": *a16
"422": *a3
"429": *a4
post:
@@ -11681,7 +11721,7 @@ paths:
schema:
$ref: "#/components/schemas/CreateCustomMetricEntryResponse"
"401": *a1
"404": *a15
"404": *a16
"422": *a3
"429": *a4
/api/custom-metrics/{id}/entries/{entryId}:
@@ -11731,7 +11771,7 @@ paths:
schema:
$ref: "#/components/schemas/UpdateCustomMetricEntryResponse"
"401": *a1
"404": &a17
"404": &a18
description: Custom metric entry not found (or owned by another user).
content:
application/json:
@@ -11763,7 +11803,7 @@ paths:
schema:
$ref: "#/components/schemas/DeleteCustomMetricEntryResponse"
"401": *a1
"404": *a17
"404": *a18
"422": *a3
"429": *a4
/api/onboarding/disclaimer:
@@ -11899,7 +11939,7 @@ paths:
schema:
$ref: "#/components/schemas/NutrientBatchEnvelope"
"401": *a1
"403": &a18
"403": &a19
description: The opt-in `nutrients` module is off for this account (errorCode `module.disabled`). Stop syncing and do
not retry; offer the enable-in-settings hint. Only run the HealthKit read-authorization flow while the
module is on.
@@ -11933,7 +11973,7 @@ paths:
schema:
$ref: "#/components/schemas/NutrientOverviewEnvelope"
"401": *a1
"403": *a18
"403": *a19
"422": *a3
"429": *a4
/api/nutrients/daily:
@@ -11969,7 +12009,7 @@ paths:
schema:
$ref: "#/components/schemas/NutrientDailySeriesEnvelope"
"401": *a1
"403": *a18
"403": *a19
"422": *a3
"429": *a4
/api/nutrients/water:
@@ -11996,7 +12036,7 @@ paths:
schema:
$ref: "#/components/schemas/NutrientWaterWriteEnvelope"
"401": *a1
"403": *a18
"403": *a19
"422": *a3
"429": *a4
/api/integrations/healthkit:
@@ -12271,7 +12311,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a3
"422": *a6
"429": *a4
delete:
tags:
@@ -13297,8 +13337,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -13772,8 +13814,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -13836,8 +13880,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -14000,8 +14046,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -14207,8 +14255,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -14445,8 +14495,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -15027,8 +15079,10 @@ components:
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque:
only ever echo a server-returned value, never parse or synthesise it."
row still carrying this exact value — a stale token fails with 409 and changes nothing. A
present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that
this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as
an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it."
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
@@ -17344,6 +17398,65 @@ components:
- data
- error
additionalProperties: false
PasskeyListEnvelope:
type: object
properties:
data:
$ref: "#/components/schemas/PasskeyListResponse"
error:
type: "null"
meta:
type: object
properties:
requestId:
type: string
additionalProperties: false
required:
- data
- error
additionalProperties: false
PasskeyListResponse:
type: array
items:
$ref: "#/components/schemas/PasskeyInfo"
PasskeyInfo:
type: object
properties:
id:
type: string
description: Row id; the handle for DELETE.
name:
type: string
description: User-supplied label, defaulting to “Passkey”.
credentialDeviceType:
type: string
description: "Authenticator device type as reported at registration: `singleDevice` for a credential bound to one
authenticator, `multiDevice` for a syncable one."
credentialBackedUp:
type: boolean
description: Whether the authenticator reported the credential as backed up (synced to the platform keychain) at
registration time. Not re-read afterwards.
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
description: Registered at.
lastUsedAt:
anyOf:
- type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
- type: "null"
description: When this passkey last completed a verified assertion; null when it has never been used to sign in. Stamped
on every successful login, so a client can render a real 'last used' rather than assuming never.
required:
- id
- name
- credentialDeviceType
- credentialBackedUp
- createdAt
- lastUsedAt
additionalProperties: false
SessionListEnvelope:
type: object
properties:
src/app/api/auth/passkeys/__tests__/route.test.ts
+32
View File
@@ -10,6 +10,14 @@
*
* The write half (the stamp on a verified assertion) is pinned in
* `src/lib/auth/__tests__/passkey.test.ts`.
*
* v1.35.1 adds the published half. The route was absent from
* `docs/api/openapi.yaml` entirely — no path entry, no schema — while iOS
* had been told to generate against one (iOS #60). The last case below
* compares the projection the route actually asks Prisma for against the
* property set the contract publishes, so the two cannot drift: a column
* added to the select without a schema entry fails, and so does a schema
* property the route never serves.
*/
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
@@ -29,6 +37,7 @@ vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
import { GET } from "../route";
import { requireAuth } from "@/lib/api-handler";
import { prisma } from "@/lib/db";
import { buildOpenApiDocument } from "@/lib/openapi/registry";
const USER = { id: "user-1", username: "u", email: "u@example.com" };
@@ -81,6 +90,29 @@ describe("GET /api/auth/passkeys", () => {
expect(Object.keys(body.data[0])).toContain("lastUsedAt");
expect(body.data[0].lastUsedAt).toBeNull();
});
it("publishes exactly the columns it selects", async () => {
await (GET as unknown as () => Promise<Response>)();
const args = vi.mocked(prisma.passkey.findMany).mock.calls[0][0];
const selected = Object.keys(args?.select ?? {}).sort();
const doc = buildOpenApiDocument() as {
paths?: Record<string, { get?: { responses?: Record<string, unknown> } }>;
components?: {
schemas?: Record<string, { properties?: Record<string, unknown> }>;
};
};
expect(
doc.paths?.["/api/auth/passkeys"]?.get,
"GET /api/auth/passkeys is not registered in the OpenAPI document",
).toBeDefined();
const published = doc.components?.schemas?.["PasskeyInfo"]?.properties;
expect(published, "PasskeyInfo schema is not emitted").toBeDefined();
expect(Object.keys(published ?? {}).sort()).toEqual(selected);
});
});
describe("primary-passkey enrollment route guards", () => {
src/lib/openapi/routes/auth.ts
+53
View File
@@ -230,6 +230,40 @@ const webauthnCredentialInfo = z
})
.meta({ id: "WebauthnMfaCredentialInfo" });
// ── Passkey list (primary sign-in credentials) ───────────────────────
// A DIFFERENT surface from `WebauthnMfaCredentialInfo` above: these are
// the credentials a passkey LOGIN asserts against, not the security keys
// registered as a second factor. The two lists are served by different
// routes and are never merged.
const passkeyInfo = z
.object({
id: z.string().describe("Row id; the handle for DELETE."),
name: z.string().describe("User-supplied label, defaulting to “Passkey”."),
credentialDeviceType: z
.string()
.describe(
"Authenticator device type as reported at registration: `singleDevice` for a credential bound to one authenticator, `multiDevice` for a syncable one.",
),
credentialBackedUp: z
.boolean()
.describe(
"Whether the authenticator reported the credential as backed up (synced to the platform keychain) at registration time. Not re-read afterwards.",
),
createdAt: z.iso.datetime({ offset: true }).describe("Registered at."),
lastUsedAt: z.iso
.datetime({ offset: true })
.nullable()
.describe(
"When this passkey last completed a verified assertion; null when it has never been used to sign in. Stamped on every successful login, so a client can render a real 'last used' rather than assuming never.",
),
})
.meta({ id: "PasskeyInfo" });
const passkeyListResponse = z
.array(passkeyInfo)
.meta({ id: "PasskeyListResponse" });
const mfaStatusResponse = z
.object({
totp: z.object({ enabled: z.boolean() }),
@@ -922,6 +956,25 @@ export const authPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/auth/passkeys": {
get: {
tags: ["Auth"],
summary: "List the caller's registered passkeys",
description:
"The passkeys registered for primary sign-in, newest first. Distinct from the second-factor security keys in `GET /api/auth/2fa/status` (`webauthn`) — a passkey replaces the password, a security key is asserted after one. `lastUsedAt` is stamped on every verified assertion and is null only for a passkey that has never signed in.",
responses: {
"200": {
description: "The caller's passkeys, newest first.",
content: {
"application/json": {
schema: dataEnvelope(passkeyListResponse, "PasskeyListEnvelope"),
},
},
},
...stdResponses,
},
},
},
"/api/auth/me/sessions": {
get: {
tags: ["Auth"],
src/lib/openapi/routes/coach.ts
+5 -1
View File
@@ -47,6 +47,7 @@ import {
stdResponses,
baseUpdatedAtField,
conflictResponse409,
invalidBaseTokenResponse,
} from "./shared";
// ── Coach cadence suggestions (v1.18.1) ──────────────────────────────
@@ -1011,8 +1012,10 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...conflictResponse409("Insights layout", "insights_layout_conflict"),
// 422 (multi-issue validation envelope) comes from stdResponses.
// 422 (multi-issue validation envelope) comes from stdResponses;
// the base-token variant of it narrows that description afterwards.
...stdResponses,
...invalidBaseTokenResponse,
},
},
delete: {
@@ -1233,6 +1236,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflictResponse409("Self-context", "about_me_conflict"),
...stdResponses,
...invalidBaseTokenResponse,
},
},
},
src/lib/openapi/routes/dashboard.ts
+2
View File
@@ -29,6 +29,7 @@ import {
stdResponses,
baseUpdatedAtField,
conflictResponse409,
invalidBaseTokenResponse,
} from "./shared";
const dashboardWidgetConfig = z.object({
@@ -143,6 +144,7 @@ export const dashboardWidgetPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflictResponse409("Dashboard layout", "dashboard_layout_conflict"),
...stdResponses,
...invalidBaseTokenResponse,
},
},
delete: {
src/lib/openapi/routes/medications/paths.ts
+2
View File
@@ -27,6 +27,7 @@ import {
errorEnvelope,
stdResponses,
conflictResponse409,
invalidBaseTokenResponse,
} from "../shared";
efficacyTargetOverrideSchema.meta({
@@ -289,6 +290,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"medication_layout_conflict",
),
...stdResponses,
...invalidBaseTokenResponse,
},
},
delete: {
src/lib/openapi/routes/mood.ts
+2
View File
@@ -31,6 +31,7 @@ import {
baseUpdatedAtField,
updatedAtTokenField,
conflictResponse409,
invalidBaseTokenResponse,
} from "./shared";
// ── Request schemas — annotated for spec emission ────────────────────
@@ -566,6 +567,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflictResponse409("Mood-tag layout", "mood_tag_layout_conflict"),
...stdResponses,
...invalidBaseTokenResponse,
},
},
},
src/lib/openapi/routes/profile.ts
+4
View File
@@ -20,6 +20,7 @@ import {
baseUpdatedAtField,
updatedAtTokenField,
conflictResponse409,
invalidBaseTokenResponse,
} from "./shared";
// v1.18.0 — module enable/disable. The PATCH request is the REAL runtime
@@ -499,6 +500,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflictResponse409("Coach preferences", "coach_prefs_conflict"),
...stdResponses,
...invalidBaseTokenResponse,
},
},
},
@@ -634,6 +636,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflictResponse409("Module preferences", "modules_conflict"),
...stdResponses,
...invalidBaseTokenResponse,
},
},
},
@@ -875,6 +878,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
"notification_prefs_conflict",
),
...stdResponses,
...invalidBaseTokenResponse,
},
},
},
src/lib/openapi/routes/shared.ts
+23 -1
View File
@@ -109,7 +109,7 @@ export const baseUpdatedAtField = z.iso
.datetime({ offset: true })
.optional()
.describe(
"Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored row still carrying this exact value — a stale token fails with 409 and changes nothing. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it.",
"Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored row still carrying this exact value — a stale token fails with 409 and changes nothing. A present-but-unparseable value fails with 422 and `meta.errorCode` = `invalid_base_updated_at` — note that this is NOT the unconditional write: sending `null` or a malformed string is rejected rather than treated as an omitted token. Treat as opaque: only ever echo a server-returned value, never parse or synthesise it.",
);
/**
@@ -138,6 +138,28 @@ export function conflictResponse409(resource: string, errorCode: string) {
};
}
/**
* The 422 a malformed `baseUpdatedAt` earns, for the write endpoints that
* accept the token in their body.
*
* Spread AFTER `...stdResponses` — the generic 422 there would otherwise
* overwrite this one and the errorCode would vanish from the contract.
*
* Worth stating outright because the shape surprises implementers: an
* unparseable token is NOT silently downgraded to the unconditional write.
* `null`, an empty string and a non-ISO string all 422. The unconditional
* write is reached by OMITTING the key, nothing else. `invalid_base_updated_at`
* had lived only in route tests since v1.32.21, so a client had no way to
* learn this from the published spec.
*/
export const invalidBaseTokenResponse = {
"422": {
description:
"Request validation failed. When the body carried a `baseUpdatedAt` that could not be parsed as an ISO-8601 timestamp — including an explicit `null` — `meta.errorCode` = `invalid_base_updated_at` and nothing was written. Omit the key entirely for the unconditional write; do not send `null` for it.",
content: { "application/json": { schema: errorEnvelope } },
},
};
// ── Standard 401 / 422 / 429 responses ───────────────────────────────
export const stdResponses = {