@stacksjs/defaults 0.70.294 → 0.70.297

package/app/Middleware/Can.ts

@@ -1,6 +1,43 @@
 import { AuthorizationException, authorize } from '@stacksjs/auth'
 import { HttpError } from '@stacksjs/error-handling'
-import { Middleware } from '@stacksjs/router'
+import { Middleware, resolveRouteModel, setRouteModelFallback } from '@stacksjs/router'
+
+/**
+ * Convention binding: parameter `site` resolves through the `Site` model
+ * (stacksjs/stacks#2231).
+ *
+ * Registered as the FALLBACK, not as a binding per name, so an app's own
+ * `defineRouteModelBinding('site', …)` still wins — scoped lookups, soft
+ * deletes and slug-instead-of-id all need to be expressible.
+ *
+ * Lives here rather than in `@stacksjs/router` because the router importing
+ * `@stacksjs/orm` would close a dependency cycle. This file is app-land, where
+ * importing the ORM is ordinary.
+ *
+ * Returning `undefined` means "no model of that name exists" and leaves the raw
+ * string to pass through exactly as before. That is what keeps this from
+ * changing the meaning of every existing `can:ability,param` route at once.
+ */
+setRouteModelFallback(async (value, { param }) => {
+  // `site` -> `Site`, `blogPost` -> `BlogPost`. Only the first character is
+  // touched: lowercasing the rest would turn `blogPost` into `Blogpost`.
+  const modelName = param.charAt(0).toUpperCase() + param.slice(1)
+
+  const orm = await import('@stacksjs/orm') as Record<string, any>
+  const model = orm[modelName]
+
+  // No model of that name — decline, so the raw string passes through exactly
+  // as it did before this existed.
+  if (!model || typeof model.find !== 'function')
+    return undefined
+
+  // `null` when the row is missing, which is deliberately NOT the same as
+  // declining: the parameter IS bound, there is simply nothing there. `Can`
+  // then authorizes with no model, which denies — the same 403 this route
+  // produced before, rather than a 404 that would tell an anonymous caller
+  // which ids exist.
+  return await model.find(Number.isNaN(Number(value)) ? value : Number(value)) ?? null
+})
 
 /**
  * Authorization Gate Middleware
@@ -44,13 +81,29 @@ export default new Middleware({
     // Prepare arguments for the gate check
     const args: any[] = []
 
-    // If a model parameter is specified, get it from route params
+    // If a model parameter is specified, resolve it to a MODEL before handing
+    // it to the gate. Passing the raw path string — which is what happened
+    // before — meant `resolveAbility()` saw a `String`, found no policy
+    // registered under that name, and fell through to the default deny. A
+    // declarative `can:view,site` could therefore never reach
+    // `SitePolicy.view(user, site)` (#2231).
     if (modelParam) {
       const routeParams = request.params || {}
-      const model = routeParams[modelParam]
+      const raw = routeParams[modelParam]
+
+      if (raw !== undefined && raw !== null && raw !== '') {
+        const resolution = await resolveRouteModel(modelParam, String(raw), request)
 
-      if (model) {
-        args.push(model)
+        if (!resolution.bound) {
+          // Nobody claims this parameter. Push the raw value, exactly as
+          // before — an app that authorizes on an id string keeps working.
+          args.push(raw)
+        }
+        else if (resolution.model !== undefined) {
+          args.push(resolution.model)
+        }
+        // Bound but absent: authorize with no model, which denies. Same 403
+        // this produced before, and it does not disclose which ids exist.
       }
     }
 

package/app/Models/SocialAccount.ts

@@ -0,0 +1,70 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+/**
+ * A social provider identity linked to a local user (stacksjs/stacks#2276).
+ *
+ * One row per (provider, provider account): a link table rather than columns
+ * on `users`, so one user can attach several providers and a provider-side
+ * email change cannot orphan the link. The unique index on
+ * `(provider, provider_user_id)` is what makes "sign in with the same GitHub
+ * account" resolve to the same local user forever.
+ *
+ * Rows are only ever written by the framework's social sign-in policy
+ * (`resolveSocialSignIn` in @stacksjs/auth) — the takeover guard lives there,
+ * not here.
+ */
+export default defineModel({
+  name: 'SocialAccount',
+  table: 'social_accounts',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  indexes: [
+    {
+      name: 'social_accounts_provider_provider_user_id_unique',
+      columns: ['provider', 'provider_user_id'],
+      unique: true,
+    },
+    {
+      name: 'social_accounts_user_id_index',
+      columns: ['user_id'],
+    },
+  ],
+
+  traits: {
+    useTimestamps: true,
+  },
+
+  belongsTo: ['User'],
+
+  attributes: {
+    provider: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(50),
+        message: { max: 'Provider must not exceed 50 characters' },
+      },
+    },
+
+    providerUserId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(255),
+        message: { max: 'Provider user id must not exceed 255 characters' },
+      },
+    },
+
+    // The address the provider reported at link time. Informational — sign-in
+    // resolves through (provider, provider_user_id), never through this.
+    providerEmail: {
+      fillable: true,
+      validation: {
+        rule: schema.string().max(255),
+        message: { max: 'Provider email must not exceed 255 characters' },
+      },
+    },
+  },
+})

package/app/Models/User.ts

@@ -3,6 +3,7 @@ import { defineModel } from '@stacksjs/orm'
 import { makeHash } from '@stacksjs/security'
 // soon, these will be auto-imported
 import { schema } from '@stacksjs/validation'
+import { PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH } from '../password-policy'
 
 export default defineModel({
   name: 'User', // defaults to the sanitized file name
@@ -98,15 +99,17 @@ export default defineModel({
       hidden: true,
       fillable: true,
       validation: {
-        rule: schema.string().required().min(6).max(255),
+        rule: schema.string().required().min(PASSWORD_MIN_LENGTH).max(PASSWORD_MAX_LENGTH),
         message: {
           required: 'Password is required',
-          min: 'Password must have a minimum of 6 characters',
-          max: 'Password must have a maximum of 255 characters',
+          min: `Password must have a minimum of ${PASSWORD_MIN_LENGTH} characters`,
+          max: `Password must have a maximum of ${PASSWORD_MAX_LENGTH} characters`,
         },
       },
 
-      factory: () => '123456',
+      // Must satisfy the rule above, or seeded users fail their own model's
+      // validation. `123456` did once the minimum moved to 8 (#2226).
+      factory: () => 'password1234',
     },
 
     avatar: {

package/app/Models/commerce/DeliveryRoute.ts

@@ -30,6 +30,7 @@ export default defineModel({
   },
 
   belongsTo: ['Driver'],
+  hasMany: ['DeliveryStop', 'DriverPing'],
 
   attributes: {
     driver: {
@@ -85,6 +86,39 @@ export default defineModel({
       },
       factory: faker => faker.date.recent().getTime(),
     },
+
+    /*
+     * Route lifecycle. `stops` and `totalDistance` describe a route that has
+     * already run; a route being followed right now needs to say so, because
+     * that is the difference between a tracking map that draws a moving
+     * vehicle and one that draws yesterday's.
+     */
+    status: {
+      order: 7,
+      fillable: true,
+      default: 'planned',
+      validation: {
+        rule: schema.enum(['planned', 'active', 'completed', 'cancelled']),
+        message: {
+          enum: 'Status must be one of: planned, active, completed, cancelled',
+        },
+      },
+      factory: faker => faker.helpers.arrayElement(['planned', 'active', 'completed']),
+    },
+
+    startedAt: {
+      order: 8,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => null,
+    },
+
+    completedAt: {
+      order: 9,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => null,
+    },
   },
 
   dashboard: {

package/app/Models/commerce/DeliveryStop.ts

@@ -0,0 +1,166 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+/**
+ * One address on a delivery route.
+ *
+ * `DeliveryRoute` records that a route happened and how far it went; this is
+ * the route itself. Without it `stops` is an integer, which is enough to bill
+ * a driver and not nearly enough to tell a customer where their order is: the
+ * link from an order to the vehicle carrying it runs through here.
+ *
+ * Sequence is the planned order. `status` is what actually happened, which
+ * diverges the moment a driver skips a building and comes back to it.
+ */
+export default defineModel({
+  name: 'DeliveryStop',
+  table: 'delivery_stops',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+
+    useSearch: {
+      displayable: ['id', 'sequence', 'status', 'address', 'etaAt'],
+      searchable: ['address', 'recipientName'],
+      sortable: ['sequence', 'etaAt', 'createdAt'],
+      filterable: ['status', 'deliveryRouteId'],
+    },
+
+    useSeeder: { count: 0 },
+
+    useApi: {
+      // A stop names a customer and their address. Staff only, both ways.
+      // Customers reach their own stop through the order tracking route,
+      // which authorises on the order's tracking token instead.
+      middleware: ['auth'],
+      uri: 'delivery-stops',
+    },
+
+    observe: true,
+  },
+
+  belongsTo: ['DeliveryRoute', 'Order'],
+
+  attributes: {
+    /** Position in the planned run, 1-based. */
+    sequence: {
+      order: 1,
+      required: true,
+      fillable: true,
+      default: 1,
+      validation: {
+        rule: schema.number().required().min(1),
+        message: { min: 'Sequence starts at 1' },
+      },
+      factory: faker => faker.number.int({ min: 1, max: 20 }),
+    },
+
+    status: {
+      order: 2,
+      required: true,
+      fillable: true,
+      default: 'pending',
+      validation: {
+        rule: schema.enum(['pending', 'en_route', 'arrived', 'completed', 'failed', 'skipped']),
+        message: {
+          enum: 'Status must be one of: pending, en_route, arrived, completed, failed, skipped',
+        },
+      },
+      factory: faker => faker.helpers.arrayElement(['pending', 'en_route', 'completed']),
+    },
+
+    address: {
+      order: 3,
+      required: true,
+      fillable: true,
+      validation: { rule: schema.string().required().max(255) },
+      factory: faker => faker.location.streetAddress(true),
+    },
+
+    /**
+     * Geocoded destination. Nullable because an address can arrive before it
+     * resolves, and a stop with no coordinates is still a stop the driver can
+     * complete; it just cannot be drawn.
+     */
+    latitude: {
+      order: 4,
+      fillable: true,
+      validation: { rule: schema.number().min(-90).max(90) },
+      factory: faker => faker.location.latitude(),
+    },
+
+    longitude: {
+      order: 5,
+      fillable: true,
+      validation: { rule: schema.number().min(-180).max(180) },
+      factory: faker => faker.location.longitude(),
+    },
+
+    recipientName: {
+      order: 6,
+      fillable: true,
+      validation: { rule: schema.string().max(255) },
+      factory: faker => faker.person.fullName(),
+    },
+
+    recipientPhone: {
+      order: 7,
+      fillable: true,
+      validation: { rule: schema.string().max(40) },
+      factory: faker => faker.phone.number(),
+    },
+
+    /** Current estimate, rewritten as the driver moves. */
+    etaAt: {
+      order: 8,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => new Date(Date.now() + 25 * 60_000).toISOString(),
+    },
+
+    /**
+     * When the customer was told the driver was close.
+     *
+     * The latch that makes "nearly there" fire once. Without it every ping
+     * inside the radius sends another text, which is roughly one text every
+     * four seconds for the last four hundred metres.
+     */
+    notifiedNearbyAt: {
+      order: 9,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => null,
+    },
+
+    /** When the driver crossed the arrival radius. */
+    arrivedAt: {
+      order: 10,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => null,
+    },
+
+    /** When the handover finished. Together with `arrivedAt`, dwell time. */
+    completedAt: {
+      order: 11,
+      fillable: true,
+      validation: { rule: schema.timestamp() },
+      factory: () => null,
+    },
+
+    /** Why a stop failed, or anything the driver needs to record. */
+    notes: {
+      order: 12,
+      fillable: true,
+      validation: { rule: schema.string().max(1000) },
+      factory: () => '',
+    },
+  },
+
+  dashboard: {
+    highlight: true,
+  },
+} as const)

package/app/Models/commerce/Driver.ts

@@ -8,7 +8,7 @@ export default defineModel({
   autoIncrement: true,
 
   belongsTo: ['User'],
-  hasMany: ['DeliveryRoute'],
+  hasMany: ['DeliveryRoute', 'DriverPing'],
 
   traits: {
     useUuid: true,
@@ -86,10 +86,80 @@ export default defineModel({
       order: 5,
       fillable: true,
       validation: {
-        rule: schema.enum(['active', 'on_delivery', 'on_break']),
+        rule: schema.enum(['active', 'on_delivery', 'on_break', 'offline']),
       },
       factory: faker => faker.helpers.arrayElement(['active', 'on_delivery', 'on_break']),
     },
+
+    /*
+     * Last known position.
+     *
+     * Denormalised from the `driver_pings` series on purpose: "where is this
+     * driver right now" is asked on every map frame and by every tracking
+     * page, and answering it with a MAX(recorded_at) subquery over a table
+     * that grows by a row every few seconds is the wrong shape. The series is
+     * the history; these three columns are the present.
+     */
+    latitude: {
+      order: 6,
+      fillable: true,
+      validation: {
+        rule: schema.number().min(-90).max(90),
+        message: {
+          min: 'Latitude must be between -90 and 90',
+          max: 'Latitude must be between -90 and 90',
+        },
+      },
+      factory: faker => faker.location.latitude(),
+    },
+
+    longitude: {
+      order: 7,
+      fillable: true,
+      validation: {
+        rule: schema.number().min(-180).max(180),
+        message: {
+          min: 'Longitude must be between -180 and 180',
+          max: 'Longitude must be between -180 and 180',
+        },
+      },
+      factory: faker => faker.location.longitude(),
+    },
+
+    /** Degrees clockwise from true north, so a map can rotate the marker. */
+    heading: {
+      order: 8,
+      fillable: true,
+      validation: {
+        rule: schema.number().min(0).max(360),
+      },
+      factory: faker => faker.number.int({ min: 0, max: 359 }),
+    },
+
+    /** Metres per second, as reported by the device. */
+    speed: {
+      order: 9,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: schema.number().min(0),
+      },
+      factory: () => 0,
+    },
+
+    /*
+     * When the last fix landed. A tracking map needs this to say "updated 4
+     * seconds ago" and, more importantly, to stop claiming a driver is at a
+     * position that is ten minutes stale.
+     */
+    lastPingAt: {
+      order: 10,
+      fillable: true,
+      validation: {
+        rule: schema.timestamp(),
+      },
+      factory: () => new Date().toISOString(),
+    },
   },
 
   dashboard: {

package/app/Models/commerce/DriverPing.ts

@@ -0,0 +1,103 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+/**
+ * One position fix from a driver's device.
+ *
+ * The append-only history behind `drivers.latitude/longitude`. A tracking map
+ * needs the present position, but everything else about a delivery needs the
+ * series: drawing the path already travelled, replaying a disputed drop,
+ * measuring how long a stop actually took, and deriving an ETA from recent
+ * speed rather than straight-line distance.
+ *
+ * Deliberately not `useSearch` (indexing a row every few seconds is pointless
+ * and expensive) and not `useApi` (writes come through
+ * `recordDriverPing`, which does the fan-out, and reads are scoped to a
+ * route). `usePrunable` keeps the table from growing without bound.
+ */
+export default defineModel({
+  name: 'DriverPing',
+  table: 'driver_pings',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+    useSeeder: { count: 0 },
+  },
+
+  belongsTo: ['Driver', 'DeliveryRoute'],
+
+  attributes: {
+    latitude: {
+      order: 1,
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.number().required().min(-90).max(90),
+        message: {
+          min: 'Latitude must be between -90 and 90',
+          max: 'Latitude must be between -90 and 90',
+        },
+      },
+      factory: faker => faker.location.latitude(),
+    },
+
+    longitude: {
+      order: 2,
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.number().required().min(-180).max(180),
+        message: {
+          min: 'Longitude must be between -180 and 180',
+          max: 'Longitude must be between -180 and 180',
+        },
+      },
+      factory: faker => faker.location.longitude(),
+    },
+
+    /** Degrees clockwise from true north. */
+    heading: {
+      order: 3,
+      fillable: true,
+      validation: { rule: schema.number().min(0).max(360) },
+      factory: faker => faker.number.int({ min: 0, max: 359 }),
+    },
+
+    /** Metres per second. */
+    speed: {
+      order: 4,
+      fillable: true,
+      default: 0,
+      validation: { rule: schema.number().min(0) },
+      factory: faker => faker.number.int({ min: 0, max: 30 }),
+    },
+
+    /**
+     * Reported horizontal accuracy in metres. Worth keeping: a fix with 800m
+     * of error should move the marker differently than one with 5m, and
+     * without this the map cannot tell them apart.
+     */
+    accuracy: {
+      order: 5,
+      fillable: true,
+      validation: { rule: schema.number().min(0) },
+      factory: faker => faker.number.int({ min: 3, max: 60 }),
+    },
+
+    /**
+     * When the device took the fix, which is not when the server received it.
+     * A driver through a tunnel sends five fixes at once on the far side, and
+     * ordering them by arrival draws a path that never happened.
+     */
+    recordedAt: {
+      order: 6,
+      required: true,
+      fillable: true,
+      validation: { rule: schema.timestamp().required() },
+      factory: () => new Date().toISOString(),
+    },
+  },
+} as const)

package/app/Models/commerce/Order.ts

@@ -29,7 +29,7 @@ export default defineModel({
     observe: true,
   },
 
-  hasMany: ['OrderItem', 'Payment', 'LicenseKey'],
+  hasMany: ['OrderItem', 'Payment', 'LicenseKey', 'DeliveryStop'],
   belongsTo: ['Customer', 'Coupon'],
 
   attributes: {
@@ -39,7 +39,18 @@ export default defineModel({
       validation: {
         rule: schema.string().required(),
       },
-      factory: faker => faker.helpers.arrayElement(['PENDING', 'PREPARING', 'READY', 'DELIVERED', 'CANCELED']),
+      /*
+       * The canonical vocabulary is `OrderStatus` in
+       * `commerce/src/orders/events.ts`, which is what `canTransition` and
+       * `emitForStatus` are keyed on. The factory used to generate
+       * PREPARING / READY / CANCELED, none of which are in that union, so
+       * seeded orders could not legally transition anywhere.
+       *
+       * The column stays a free string rather than an enum: existing
+       * databases hold the old spellings, and adding a CHECK constraint here
+       * would fail their next migration rather than fix their data.
+       */
+      factory: faker => faker.helpers.arrayElement(['PENDING', 'PROCESSING', 'SHIPPED', 'OUT_FOR_DELIVERY', 'DELIVERED']),
     },
 
     totalAmount: {
@@ -141,8 +152,38 @@ export default defineModel({
       },
     },
 
-    appliedCouponId: {
+    /**
+     * Unguessable handle for the customer-facing tracking page.
+     *
+     * A tracking URL is opened from an SMS, on a phone, by someone who is not
+     * signed in, so it authorises on possession of this token. Sequential
+     * order ids would let anyone walk the table.
+     */
+    trackingToken: {
       order: 13,
+      unique: true,
+      fillable: true,
+      validation: { rule: schema.string().max(64) },
+      factory: faker => faker.string.alphanumeric({ length: 32 }),
+    },
+
+    /** Geocoded delivery destination, so the map has somewhere to point. */
+    deliveryLatitude: {
+      order: 14,
+      fillable: true,
+      validation: { rule: schema.number().min(-90).max(90) },
+      factory: faker => faker.location.latitude(),
+    },
+
+    deliveryLongitude: {
+      order: 15,
+      fillable: true,
+      validation: { rule: schema.number().min(-180).max(180) },
+      factory: faker => faker.location.longitude(),
+    },
+
+    appliedCouponId: {
+      order: 16,
       fillable: true,
       validation: {
         rule: schema.string(),