@stacksjs/defaults 0.75.227 → 0.75.229

package/ai/skills/stacks-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 670 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 672 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-auth/ACCOUNT-WORKFLOWS.md

@@ -127,18 +127,35 @@ Evidence: `tests/rbac-default-store.test.ts`, `rbac-guard-sync.test.ts`,
 
 ## Social identity linking and referrals
 
-`resolveSocialSignIn(provider, identity, store?)` resolves durable provider-id
-links first, then applies `config.auth.socials.matching`: link/create/refuse.
-An email match is subject to the identity verification policy; copying an email
-from a provider payload is not sufficient proof to link an existing account.
-Use SocialSignInRefusedError to distinguish configured refusal from infrastructure
-failure. `stacks-socials` owns provider authorization and callback exchange.
+`resolveSocialSignIn(provider, identity, store?, { tx? })` resolves durable
+provider-id links first, then applies `config.auth.socials.matching`:
+link/create/refuse. An email match links only when the provider vouches for the
+address (`emailVerified === true`, else `'unverified-provider-email'`) AND the
+local account verified it (`users.email_verified_at`, else
+`'unverified-local-email'`). Neither guard is configurable. A user created from
+a provider-verified address starts with `email_verified_at` set (`createUser`
+receives `emailVerified`). Every store method receives the `tx`, so lookup, user
+and link commit together; a store may implement `isUserEmailVerified(userId, tx)`
+and otherwise gets the default that reads `users.email_verified_at`
+(`defaultSocialSignInStore()` is exported). Use SocialSignInRefusedError's
+`reason` to distinguish refusal from infrastructure failure. `stacks-socials`
+owns provider authorization, the flow state and callback exchange.
+
+After resolving the user, a redirect flow hands the browser a one-use code, not
+tokens: `createSessionHandoff(userId, { bindTo: 'cookie' | { challenge } })`
+returns `{ code, cookie, expiresAt }` (60 seconds, single use, bound to the
+HttpOnly cookie or to the SHA-256 hex of a native client's verifier), and
+`redeemSessionHandoff(code, secret)` returns `{ userId, data } | null` once.
+`readSessionHandoffCookie(header, code)` / `clearSessionHandoffCookie(code)` read
+and clear the binding cookie. The default `POST /auth/handoff`
+(SessionHandoffAction) redeems and mints the session; mint nothing before it.
 
 Referrals expose createReferralCode(ownerId), attributeReferral(newUserId, input),
 qualifyReferral(referredUserId) and referralSummary(ownerId), with optional
 database injection. Normalize/attribute at registration and qualify at the
 application's real conversion milestone. Attribution alone is not a paid reward.
 
-Source: `src/socials.ts`, `referrals.ts`. Evidence: `tests/social-linking.test.ts`,
+Source: `src/socials.ts`, `session-handoff.ts`, `referrals.ts`. Evidence:
+`tests/social-linking.test.ts`, `social-callback-flow.test.ts`,
 `referrals.test.ts`. All account features remain subject to model loading,
 selected route bundles, config gates and applied migrations.

package/ai/skills/stacks-auth/SKILL.md

@@ -66,8 +66,8 @@ declaring `useAuth` can hold tokens - not only `User`.
 - `tokenCan(scope)` / `tokenCanAll` / `tokenCanAny` / `tokenAbilities` - check
   the current request's token.
 - `revokeToken`, `revokeTokenById`, `revokeAllTokens(id, type?)`,
-  `revokeOtherTokens(id, type?)` - revocation also revokes the paired refresh
-  token, which a raw row delete does not.
+  `revokeOtherTokens(id, type?, { exceptTokenId? })` - revocation also revokes
+  the paired refresh token, which a raw row delete does not.
 - `setTrailActor(id)` - attribute writes in a queue job or CLI run that has no
   request to read a user from.
 
@@ -106,7 +106,7 @@ routes: minting and revoking both carry semantics a generic route does not.
 - `Auth.revokeToken(token: string): Promise<void>`
 - `Auth.revokeTokenById(tokenId: number): Promise<void>`
 - `Auth.revokeAllTokens(userId?: number): Promise<void>`
-- `Auth.revokeOtherTokens(userId?: number): Promise<void>`
+- `Auth.revokeOtherTokens(userId?: number, { exceptTokenId? }): Promise<{ keptTokenId: number | null }>` - keeps `exceptTokenId`, else the request's own token; when neither resolves it revokes every token (fail closed)
 - `Auth.pruneExpiredTokens(): Promise<number>`
 - `Auth.pruneRevokedTokens(): Promise<number>`
 - `Auth.rotateToken(oldToken: string): Promise<AuthToken | null>`
@@ -138,7 +138,7 @@ routes: minting and revoking both carry semantics a generic route does not.
 - `revokeToken(plainTextToken): Promise<void>`
 - `revokeTokenById(tokenId): Promise<void>`
 - `revokeAllTokens(userId): Promise<void>`
-- `revokeOtherTokens(userId): Promise<void>`
+- `revokeOtherTokens(userId, type?, { exceptTokenId? }): Promise<{ keptTokenId: number | null }>` - same rule as `Auth.revokeOtherTokens`
 - `deleteExpiredTokens(): Promise<number>`
 - `deleteRevokedTokens(daysOld?): Promise<number>`
 
@@ -318,10 +318,37 @@ Internal: database-backed `sessions` rows with expiry, optional IP/User-Agent fi
 ```typescript
 const actions = passwordResets(email)
 await actions.sendEmail()
+// or: an invitation's first password, a custom expiry, your own delivery
+await actions.sendEmail({
+  purpose: 'setup',                       // 'reset' (default) | 'setup'
+  expiresAt: new Date(Date.now() + 3 * 864e5),
+  deliver: async ({ purpose, userId, email, token, url, expiresAt }) => { /* localized mail, ledger */ },
+})
 const valid = await actions.verifyToken(token)
 const result = await actions.resetPassword(token, newPassword)
 ```
 
+`deliver` runs after the token commits, instead of the framework mail; the
+`token`/`url` are the live credential, never log them. `sendEmail` stays a
+silent no-op for unknown or throttled addresses (anti-enumeration).
+
+### One credential sweep (password/credentials.ts)
+
+- `revokeAccountCredentials(userId, { exceptTokenId?, exceptSessionId?, tx? })`
+  stamps `password_changed_at` and revokes two-factor challenges, magic links,
+  OAuth grants and codes, access/refresh tokens and sessions, in one transaction
+  (joins the caller's when `tx` is given; a `tx` outside its transaction
+  throws). The kept token and its refresh token are re-bound to the stamp.
+  Returns `{ passwordChangedAt, keptTokenId }`. `resetPassword` runs it.
+- `changePassword(userId, current, next, { keepTokenId?, keepSessionId?, notify? })`
+  verifies `current`, commits only if that hash is still stored, runs the sweep,
+  then notifies after commit (`notify`: `true` = the `password-changed` mail, a
+  function = yours, `false` = nothing). Returns `{ success: true, keptTokenId }`
+  or `{ success: false, reason: 'invalid-current-password' | 'user-not-found' | 'invalid-new-password' }`.
+  Enforce the new password's policy first.
+- Any other path that changes how an account proves who it is (recovery, an
+  admin forcing a sign-out, an email change) should call the sweep too.
+
 ## Registration (register.ts)
 
 - `register(credentials: NewUser): Promise<{ token: AuthToken }>`
@@ -398,9 +425,12 @@ const locked = await RateLimiter.isRateLimited(email)
 await RateLimiter.resetAttempts(email)
 ~~~
 
-Five failed attempts lock an email for fifteen minutes. The configured store
-selects atomic Redis when the cache config selects Redis, otherwise process-local
-memory. `useSharedStore(options?)` explicitly chooses Redis;
+Five failed attempts (`maxFailedAttempts()`, times
+`config.security.rateLimit.scale` / `STACKS_RATE_LIMIT_SCALE`) lock an email for
+fifteen minutes. The configured store selects atomic Redis when the cache config
+selects Redis, wrapped in `FallbackRateLimiterStore` so a Redis outage degrades
+to process memory (warned once) instead of failing every sign-in; otherwise
+process-local memory. `useSharedStore(options?)` explicitly chooses Redis;
 `useStore(custom)` installs a store with atomic recordFailedAttempt;
 `useMemoryStore()` and `useConfiguredStore()` reset that choice.
 Shared deployments need a shared atomic store. Partial counters expire, and
@@ -528,6 +558,10 @@ is the declarative form and the one the ability-name completions come from.
 - `DELETE /auth/tokens/{id}` → RevokeTokenAction (auth middleware)
 - `GET /me` → GetMeAction (auth middleware)
 - `POST /logout` → LogoutAction (auth middleware)
+- Social bundle: `GET /auth/{provider}` → SocialRedirectAction (issues the
+  browser-bound OAuth state), `GET|POST /auth/{provider}/callback` →
+  SocialCallbackAction (redeems it, redirects with `#stx_handoff=<code>`),
+  `POST /auth/handoff` → SessionHandoffAction (redeems the code for the session)
 
 ## User Model Traits
 
@@ -545,7 +579,7 @@ traits: {
 
 - Auth depends on `@stacksjs/ts-auth` for TOTP and passkey functions
 - Password hashing defaults to bcrypt with 12 rounds (config/hashing.ts)
-- Rate limiting uses a process-local memory store by default. Production deployments with multiple workers should configure the atomic Redis store or provide a custom atomic store.
+- Rate limiting uses a process-local memory store unless `config/cache.ts` selects Redis, which the lockout and route limits then share. Production deployments with multiple workers should configure Redis or provide a custom atomic store. Test suites raise `config.security.rateLimit.scale` rather than disabling limits.
 - Session auth is database-backed through the `sessions` table, so it survives server restarts and is shared across workers.
 - New personal and delegated access tokens are opaque 40-byte hex bearers hashed at rest. Legacy `jwt:encryptedId` bearers remain readable during migration.
 - Token validation hashes the bearer directly. Do not parse or expose token contents, and never log plaintext bearer values.

package/ai/skills/stacks-browser/SKILL.md

@@ -44,16 +44,38 @@ Browser state uses imported storage helpers, not direct document/window mutation
 inside STX scripts.
 
 refreshSession coalesces concurrent refresh attempts. A server refusal clears the
-session and returns false; a transport failure throws and keeps the existing
-credential. authFetch retries the eligible request after refresh using the native
-credential/CSRF flow. Cookie/session behavior and refresh-token availability
-depend on server browser-session policy. A fixed-lifetime login cannot be made
-renewable by keeping an old client refresh token.
+session and returns false; a network failure, 5xx, 408 or 429 keeps the existing
+credential and returns false. authFetch retries the eligible request after
+refresh using the native credential/CSRF flow. Cookie/session behavior and
+refresh-token availability depend on server browser-session policy. A
+fixed-lifetime login cannot be made renewable by keeping an old client refresh
+token.
+
+Only a 401 ends a session. fetchAuthUser shares one in-flight /api/me request
+between concurrent callers. A network failure, 5xx, 403 or other non-401 answer
+keeps token, user and isAuthenticated and resolves the last known user. 403 is
+an authorization decision about a recognised identity, so the app should show
+a forbidden state, not send the user to log in again. An unchanged /me answer
+keeps the same user object, so effects do not re-run. A same-origin authFetch
+401 that refresh cannot cure re-checks /api/me instead of signing out (signed
+URLs and step-up checks also answer 401). Only that check's 401 clears the
+session. A burst of such 401s makes one /me request, one clear and one
+onSessionExpired(listener) call. Answers to requests sent before a new sign-in
+are ignored. logout() does not fire onSessionExpired.
 
 completeSocialLogin applies the native handoff through the same storage refs and
-strips its URL fragment. Use socialHandoffRedirect on the server; a hand-built
-inline script writing token/user keys duplicates the encoding/security contract.
+strips its URL fragment. The default callback sends a one-use stx_handoff code.
+Called with no argument, completeSocialLogin redeems it with a credentialed POST
+to /auth/handoff (AUTH_HANDOFF_PATH); a refused or unreachable redemption
+resolves null and leaves the existing session alone. A stx_auth pack from a
+custom callback still works. Use socialHandoffRedirect on the server; a
+hand-built inline script writing token/user keys duplicates the
+encoding/security contract.
+
 authGuard controls client navigation; guard server pages/actions independently.
+With a stored but unconfirmed token it checks /api/me instead of redirecting,
+so a network blip on page load keeps the user on the page. A 401 then, or any
+later session expiry on that page, redirects to /login once.
 
 ## API transports and errors
 
@@ -88,5 +110,6 @@ composable skill instead of copying another fixed inventory of globals.
 
 `storage/framework/core/browser/src/index.ts`, auto-init.ts, model-loader.ts,
 composables/useAuth.ts/useApi.ts/csrf.ts/request-error.ts and utils/fetch.ts.
-Tests: client-bundle-safety.test.ts, use-auth-refresh.test.ts, csrf.test.ts,
+Tests: client-bundle-safety.test.ts, use-auth-refresh.test.ts (refresh, session
+resilience, burst expiry, authGuard, handoff code), auth.test.ts, csrf.test.ts,
 request-error.test.ts and api-url.test.ts under core/browser/tests.

package/ai/skills/stacks-cli/SKILL.md

@@ -129,6 +129,14 @@ inspection, append a newline, and complete before an immediate `process.exit()`.
 The narrow import needs no application configuration. Use `log` for application
 logging with levels, context and transports.
 
+For large results or piped output, use `await printAsync(...args)` and
+`await printErrorAsync(...args)` from the same entrypoint. Their signatures are
+`(...args: unknown[]) => Promise<void>`. They append a newline, preserve Node
+formatting, wait for stream writes under backpressure, and reject write errors
+such as `EPIPE`. Await them before `process.exit()`. The synchronous helpers
+remain for small, bounded immediate-exit messages and may throw `EAGAIN` when
+a nonblocking pipe is full. These helpers are also exported by `@stacksjs/cli`.
+
 ## Output Formatting
 
 Via `@stacksjs/utils` color functions (available in CLI context):

package/ai/skills/stacks-database/SKILL.md

@@ -371,6 +371,10 @@ or dialect-aware raw helpers. sql.as validates an alias; raw text remains a
 trusted-code operation. sqlDateTime/parseSqlDateTime provide the canonical
 application timestamp representation. Mixing SQLite datetime text with
 application ISO text in raw comparisons can give wrong expiry boundaries.
+parseSqlDate(value) reads a DATE column back as the YYYY-MM-DD it stores,
+whether the driver built the Date at UTC midnight (Bun's Postgres driver) or at
+the host's local midnight; toISOString().slice(0, 10) shifts the latter a day
+back east of UTC. Null for missing, invalid or impossible input.
 Source: core/database/src/types.ts and sql-helpers.ts; see stacks-query-builder
 for typed tables, raw binding, transaction handles and replica routing.
 

package/ai/skills/stacks-datetime/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-datetime
-description: Use when working with dates and times in Stacks - the DateTime class with Carbon-like API (add/sub, comparison, formatting, start/end of day/month/year), date parsing, format tokens, or timezone handling. Covers @stacksjs/datetime.
+description: Use when working with dates and times in Stacks - the DateTime class with Carbon-like API (add/sub, comparison, formatting, start/end of day/month/year), date parsing, format tokens, timezone handling, wall-clock times in a named zone across DST, or YYYY-MM-DD calendar dates (today in a zone, day arithmetic, ISO weeks). Covers @stacksjs/datetime.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -24,10 +24,14 @@ export { parse } from './parse'
 export { format as dateFormat } from './format'  // convenience alias
 ```
 
-Three source files:
+Source files:
 - `now.ts` - `DateTime` class and `now()` helper
 - `format.ts` - standalone `format()` function with token-based formatting and timezone support
 - `parse.ts` - standalone `parse()` function with token-based parsing
+- `zone.ts` - wall clock in a named zone to an instant and back (`zonedTimeToUtc`, `isoInZone`, `zoneOffsetMinutes`)
+- `calendar.ts` - `addCalendarMonths` and the `YYYY-MM-DD` helpers (`todayIn`, `addDays`, `daysBetween`, `startOfIsoWeek`, `isCalendarDate`, `isTimeZone`, `minutesUntil`)
+- `local.ts` - `localDateTime` (site and organization clocks)
+- `schedule.ts` - recurrences, coverage and local reporting periods
 
 ## DateTime Class (`now.ts`)
 
@@ -252,10 +256,70 @@ The root additionally exports `zoneOffsetMinutes(instant, timeZone)`,
 `addCalendarMonths(date, count, { utc? })`. A wall-clock string has no supplied
 offset; the named IANA zone converts it into an instant. `isoInZone` retains
 that zone's offset in serialized output rather than merely displaying a date.
-Review `zone.ts` and its DST behavior when ambiguous/gap local times matter.
 `addCalendarMonths` clones and clamps the day; ordinary `DateTime.addMonths`
 preserves native Date overflow instead. Do not interchange those contracts.
 
+`zonedTimeToUtc` resolves DST edges the same way in every zone (RFC 5545 and
+Temporal's `'compatible'` rule):
+
+| Wall clock | Zone | Result | Why |
+|---|---|---|---|
+| `2026-10-25T02:30` | `Europe/Berlin` | `2026-10-25T00:30:00Z` (`+02:00`) | Repeated hour: the EARLIER instant |
+| `2026-11-01T01:30` | `America/New_York` | `2026-11-01T05:30:00Z` (`-04:00`) | Repeated hour: the EARLIER instant |
+| `2026-03-29T02:30` | `Europe/Berlin` | `2026-03-29T01:30:00Z`, shown as `03:30+02:00` | Skipped: read with the offset before the gap |
+| `2026-03-08T02:30` | `America/New_York` | `2026-03-08T07:30:00Z`, shown as `03:30-04:00` | Skipped: read with the offset before the gap |
+
+Releases up to 0.75.228 returned the LATER instant of a repeated hour in zones
+at or east of UTC (Berlin, London, Sydney) while New York got the earlier one.
+
+```typescript
+import { zonedTimeToUtc } from '@stacksjs/datetime'
+
+zonedTimeToUtc('2026-10-01T20:00:00', 'America/New_York').toISOString() // '2026-10-02T00:00:00.000Z'
+zonedTimeToUtc('2026-10-25T02:30', 'Europe/Berlin').toISOString()       // '2026-10-25T00:30:00.000Z'
+```
+
+## Calendar dates (`YYYY-MM-DD` strings)
+
+A date column, a training day or a membership period is a day on a calendar,
+not an instant. Keep it a `YYYY-MM-DD` string: these helpers do their arithmetic
+on the UTC calendar (every day 24 hours, whatever the server zone) and only meet
+a time zone where a real clock is involved (`todayIn`, `minutesUntil`). Source:
+`src/calendar.ts`.
+
+```typescript
+import { addDays, daysBetween, isCalendarDate, isTimeZone, minutesUntil, startOfIsoWeek, todayIn } from '@stacksjs/datetime'
+
+isCalendarDate('2026-02-31')          // false (a type guard; also rejects '2026-2-3')
+isTimeZone('Europe/Berlin')           // true  (a type guard; '' and unknown zones are false)
+todayIn('Pacific/Auckland', now)      // the date there, e.g. '2026-10-19' while UTC is on the 18th
+addDays('2026-12-31', 1)              // '2027-01-01'
+daysBetween('2026-10-18', '2026-10-25') // 7 (signed: negative when the second is earlier)
+startOfIsoWeek('2026-10-18')          // '2026-10-12' (the Monday; a Sunday belongs to the week before)
+
+// Real minutes from now until 09:00 on a date in a zone, correct across DST:
+minutesUntil('2026-10-25', '09:00', 'Europe/Berlin', new Date('2026-10-24T22:00:00Z')) // 600, not 540
+```
+
+- Every helper throws `RangeError` for an impossible date, a malformed clock
+  time (`HH:mm` or `HH:mm:ss`, 00-23 hours), an unknown zone or an invalid
+  instant. Validate input with `isCalendarDate` / `isTimeZone` first.
+- `todayIn` takes one zone. To fall back (a site's zone, then its
+  organization's, then UTC) use `localDateTime(now, ...zones).date`.
+- `minutesUntil` keeps the seconds of `now` as a fraction; round where you
+  display or compare. Negative once the moment has passed.
+- `addDays` refuses a result past 9999-12-31.
+
+### Reading `DATE` columns: `parseSqlDate` (`@stacksjs/database`)
+
+Drivers return a `DATE` column as a JS `Date`, at UTC midnight (Bun's Postgres
+driver) or at the host's local midnight (others). `date.toISOString().slice(0, 10)`
+is only right for the first: on a host east of UTC a local-midnight `Date` moves
+to the day before. `parseSqlDate(value)` from `@stacksjs/database` returns the
+stored `YYYY-MM-DD` either way (local midnight reads local fields, anything else
+UTC fields), keeps the date part of strings, and returns null for missing,
+invalid or impossible input. It sits beside `parseSqlDateTime`.
+
 ## Current-time helper example
 
 ```typescript