@quickback-dev/cli 0.66.25 → 0.67.1
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.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +4 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +2 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +1 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/docs/api/actions.md +1 -1
- package/dist/skill/docs/api/crud.md +8 -0
- package/dist/skill/docs/api/errors.md +9 -6
- package/dist/skill/docs/api/openapi.md +1 -0
- package/dist/skill/docs/api/typescript.md +3 -1
- package/dist/skill/docs/configure/providers.md +15 -0
- package/dist/skill/docs/define/access.md +12 -1
- package/dist/skill/docs/define/actions/scoped-db.md +80 -4
- package/dist/skill/docs/define/areas.md +3 -1
- package/dist/skill/docs/define/arrows.md +70 -9
- package/dist/skill/docs/define/fga.md +4 -2
- package/dist/skill/docs/define/firewall.md +6 -3
- package/dist/skill/docs/define/permissions.md +1 -1
- package/dist/skill/docs/define/schema.md +1 -1
- package/dist/skill/docs/define/scopes.md +1 -1
- package/dist/skill/docs/define/triggers.md +13 -1
- package/dist/skill/docs/platform/auth/plugins/subscriptions.md +23 -1
- package/dist/skill/docs/platform/auth/security.md +23 -1
- package/dist/skill/docs/platform/database/neon.md +3 -1
- package/dist/skill/docs/platform/push/index.md +1 -1
- package/dist/skill/docs/ui/account/features/admin.md +29 -0
- package/dist/skill/docs/ui/account/features/sessions.md +2 -0
- package/dist/skill/docs/ui/account/hooks.md +49 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +1 -1
- package/src/skill/docs/api/crud.md +8 -0
- package/src/skill/docs/api/errors.md +9 -6
- package/src/skill/docs/api/openapi.md +1 -0
- package/src/skill/docs/api/typescript.md +3 -1
- package/src/skill/docs/configure/providers.md +15 -0
- package/src/skill/docs/define/access.md +12 -1
- package/src/skill/docs/define/actions/scoped-db.md +80 -4
- package/src/skill/docs/define/areas.md +3 -1
- package/src/skill/docs/define/arrows.md +70 -9
- package/src/skill/docs/define/fga.md +4 -2
- package/src/skill/docs/define/firewall.md +6 -3
- package/src/skill/docs/define/permissions.md +1 -1
- package/src/skill/docs/define/schema.md +1 -1
- package/src/skill/docs/define/scopes.md +1 -1
- package/src/skill/docs/define/triggers.md +13 -1
- package/src/skill/docs/platform/auth/plugins/subscriptions.md +23 -1
- package/src/skill/docs/platform/auth/security.md +23 -1
- package/src/skill/docs/platform/database/neon.md +3 -1
- package/src/skill/docs/platform/push/index.md +1 -1
- package/src/skill/docs/ui/account/features/admin.md +29 -0
- package/src/skill/docs/ui/account/features/sessions.md +2 -0
- package/src/skill/docs/ui/account/hooks.md +49 -1
|
@@ -908,7 +908,9 @@ from the relationship table under its own policy.
|
|
|
908
908
|
— exactly where the API applies the same binding.
|
|
909
909
|
- **Permissions.** A `{ permission }` arm expands as the API expands it; arrow
|
|
910
910
|
hops become `qb_arrow_…` helpers (recursive arrows are a `maxDepth`-bounded
|
|
911
|
-
closure that re-checks the tenant on every row
|
|
911
|
+
closure that re-checks the tenant on every row; a relation-backed arrow keeps
|
|
912
|
+
the hop's rows whose FK is in the relationship's `qb_rel_…` set), called by
|
|
913
|
+
the API too.
|
|
912
914
|
- **Still API-only.** Literal status filters (a conjunct would refuse
|
|
913
915
|
status-changing updates, because PostgreSQL checks an UPDATE's new row against
|
|
914
916
|
the read policy) and claims the Worker never writes into the transaction —
|
|
@@ -55,7 +55,7 @@ With `push.defaultSchema: true`, the compiler injects a hardened, owner-scoped `
|
|
|
55
55
|
|
|
56
56
|
- **INTERNAL-only reads** — the crypto fields (`endpoint`, `p256dh`, `auth`) never leave the worker via any HTTP path. A `views.mine` projection exposes only `id`, `userAgent`, `lastSeenAt`, `createdAt` for "Your devices" UIs.
|
|
57
57
|
- **Owner firewall** — `owner_id` is auto-stamped on create; user A can never read or delete user B's subscription.
|
|
58
|
-
- **Create-time validation** — the endpoint must be `https:` (the worker POSTs VAPID-signed requests at that URL, so an arbitrary endpoint is an SSRF primitive), `p256dh` must decode to a 65-byte uncompressed P-256 point, and `auth` to a 16-byte secret. The `https:` check is not the whole SSRF story: at send time the push sender
|
|
58
|
+
- **Create-time validation** — the endpoint must be `https:` (the worker POSTs VAPID-signed requests at that URL, so an arbitrary endpoint is an SSRF primitive), `p256dh` must decode to a 65-byte uncompressed P-256 point, and `auth` to a 16-byte secret. The `https:` check is not the whole SSRF story: at send time the push sender runs the endpoint through the same destination policy as [outbound webhooks](/platform/webhooks/outbound) (`src/lib/webhooks/url-policy.ts`): every IANA special-purpose IPv4/IPv6 range (loopback, link-local and the cloud metadata address, RFC 1918, CGNAT, IPv4-mapped, ULA, NAT64, 6to4, Teredo), plus `localhost`, `.local`, `.internal`, `.home.arpa` and single-label names. Unlike webhooks it does **not** resolve DNS, so a public hostname that resolves to a private address is not caught. Together — **https + the destination policy** — this narrows the SSRF surface; treat it as defense-in-depth, not a guarantee that SSRF is impossible.
|
|
59
59
|
- **Proven identity tags** — a `tags` column is stamped **server-side** from `ctx`: `user:<id>`, and — only when the request carries a scoped token — `scope:<kind>:<subject>` plus one `scope:<kind>:<instance>#<role>` per scope role the verified claim grants (the same dialect realtime tickets use). Client-supplied tags are ignored: they drive fan-out targeting. **Org roles are never stamped** — a device is user-owned, and org audiences are resolved from live membership at send time; see [Targeting](#targeting).
|
|
60
60
|
- **Rate limit + cap** — creates are limited to 10/minute per caller, and only the newest 10 live subscriptions per user are kept (older rows are soft-deleted, so a user's new device always works).
|
|
61
61
|
|
|
@@ -67,6 +67,35 @@ So organization creation asks for an `ownerUserId`, seats that user, and never s
|
|
|
67
67
|
|
|
68
68
|
An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
|
|
69
69
|
|
|
70
|
+
## Requiring a second factor
|
|
71
|
+
|
|
72
|
+
Operator accounts are the highest-value targets in a deployment, and CASA / ASVS require multi-factor authentication on every administrative interface. `operatorMfa` enforces it:
|
|
73
|
+
|
|
74
|
+
```ts title="quickback.config.ts"
|
|
75
|
+
providers: {
|
|
76
|
+
auth: defineAuth("better-auth", {
|
|
77
|
+
operatorMfa: true,
|
|
78
|
+
plugins: ["passkey", "admin"],
|
|
79
|
+
}),
|
|
80
|
+
},
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/auth/v1/admin/*` operator routes, Better Auth's own admin endpoints (`list-users`, `set-role`, `ban-user`), and the sysadmin cross-tenant bypass. The Account UI keeps working, so the enrolment path is short:
|
|
84
|
+
|
|
85
|
+
1. Sign in with a password (or magic link / OTP) as usual.
|
|
86
|
+
2. Register a passkey at `/account/passkeys/setup`.
|
|
87
|
+
3. Sign out, then sign back in **with the passkey**.
|
|
88
|
+
|
|
89
|
+
How it works: the compiler adds a `session.amr` column (RFC 8176, *Authentication Methods Reference*) and a `session.create.before` hook that stamps `passkey` when the session comes from `/passkey/verify-authentication` and `mfa` when it comes from `/two-factor/verify-*`. Nothing else sets it, and it is not client-settable. The auth middleware reads it on the session lane and copies it into the JWT fast-path claims, so bearer callers are gated identically.
|
|
90
|
+
|
|
91
|
+
Things to know:
|
|
92
|
+
|
|
93
|
+
- **Requires `passkey` or `twoFactor`.** The compile fails otherwise: without a second factor to enrol, every operator would be locked out.
|
|
94
|
+
- **Passkey sign-in only.** A user who has a passkey but signs in with a password is not MFA'd; the session has to be created by the passkey assertion.
|
|
95
|
+
- **Two-factor "trust this device"** skips the verify endpoint, so a trusted-device sign-in does not count. Operators should not use it.
|
|
96
|
+
- **API keys never satisfy it.** An operator's API key is a single factor; operator routes reject it with `MFA_REQUIRED`.
|
|
97
|
+
- **Existing projects** get a new `amr` column on the auth `session` table on the next compile; apply the generated auth migration before deploying.
|
|
98
|
+
|
|
70
99
|
## Custom Admin Domain
|
|
71
100
|
|
|
72
101
|
Give the admin panel its own subdomain with `adminDomain`:
|
|
@@ -14,6 +14,8 @@ Users can see all devices where they're currently logged in, including:
|
|
|
14
14
|
|
|
15
15
|
Users can revoke any session except their current one. This immediately invalidates the session token.
|
|
16
16
|
|
|
17
|
+
Two events revoke other sessions without a click: changing the password from the profile page (the UI sends `revokeOtherSessions: true`), and resetting it through the forgot-password flow (the server default `revokeSessionsOnPasswordReset: true`, see [Session Freshness and Password Reset](/platform/auth/security#session-freshness-and-password-reset)).
|
|
18
|
+
|
|
17
19
|
## Related
|
|
18
20
|
|
|
19
21
|
- [Environment Variables](/ui/account/environment-variables)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Auth Hooks
|
|
2
2
|
|
|
3
|
-
Quickback discovers project-level auth hooks at `quickback/hooks/`. Most `before-`/`after-` lifecycle hooks wire directly into [Better Auth's `databaseHooks`](https://www.better-auth.com/docs/concepts/database#database-hooks); `before-email-otp-activate.ts` is a narrower compiler-owned atomic ceremony, and the `resolve-*` hooks are trusted server resolvers called from generated middleware (OAuth) or the email send. Use them for post-signup bootstrap, signup gating, tenant resolution, and per-recipient email context.
|
|
3
|
+
Quickback discovers project-level auth hooks at `quickback/hooks/`. Most `before-`/`after-` lifecycle hooks wire directly into [Better Auth's `databaseHooks`](https://www.better-auth.com/docs/concepts/database#database-hooks); `before-email-otp-activate.ts` is a narrower compiler-owned atomic ceremony, and the `resolve-*` hooks are trusted server resolvers called from generated middleware (OAuth) or the email send. `before-invitation-create.ts` is the organization plugin's own `beforeCreateInvitation` hook. Use them for post-signup bootstrap, signup gating, tenant resolution, and per-recipient email context.
|
|
4
4
|
|
|
5
5
|
The classic case is multi-tenant: when `account.auth.organizations: true` is set, a freshly signed-up user has no `activeOrganizationId`, so every authenticated `/api/v1/*` returns `403 ORG_REQUIRED`. An `after-user-create` hook can auto-provision a personal workspace + member row so the next request just works.
|
|
6
6
|
|
|
@@ -14,6 +14,7 @@ quickback/
|
|
|
14
14
|
before-email-otp-activate.ts
|
|
15
15
|
after-session-create.ts
|
|
16
16
|
after-admin-user-create.ts
|
|
17
|
+
before-invitation-create.ts
|
|
17
18
|
resolve-oauth-context.ts
|
|
18
19
|
resolve-email-context.ts
|
|
19
20
|
```
|
|
@@ -29,6 +30,7 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
|
|
|
29
30
|
| `before-email-otp-activate.ts` | Atomic email-OTP activation before `user.update` | `{ userId, email, user }` | `void \| false` |
|
|
30
31
|
| `after-session-create.ts` | `databaseHooks.session.create.after` | `Session` | `void` |
|
|
31
32
|
| `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
|
|
33
|
+
| `before-invitation-create.ts` | `organizationHooks.beforeCreateInvitation` | `{ invitation, inviter, organization }` | `void \| { data?: Partial<Invitation> }` |
|
|
32
34
|
| `resolve-oauth-context.ts` | OAuth bearer middleware | OAuth identity + session | Partial `AppContext` tenant fields |
|
|
33
35
|
| `resolve-email-context.ts` | emailOTP `sendVerificationOTP` | `{ email, type, name }` | Extra fields merged into the email template context |
|
|
34
36
|
|
|
@@ -201,6 +203,51 @@ Notes:
|
|
|
201
203
|
- This is **not** a Better Auth `databaseHook` — it's consumed only by the
|
|
202
204
|
emailOTP send, so it adds no signup/session latency.
|
|
203
205
|
|
|
206
|
+
## Gate or reroute an organization invitation
|
|
207
|
+
|
|
208
|
+
`POST /auth/v1/organization/invite-member` sends mail to whatever address the
|
|
209
|
+
caller types, from generated code — a sandbox or demo plan that contains every
|
|
210
|
+
other send through a policy cannot reach it. Add
|
|
211
|
+
`quickback/hooks/before-invitation-create.ts` and the compiler wires it as the
|
|
212
|
+
organization plugin's `organizationHooks.beforeCreateInvitation`. Throw to
|
|
213
|
+
abort; return `{ data: { email } }` to redirect the recipient. Better Auth
|
|
214
|
+
merges `data` onto the invitation row, so any invitation field (`role`,
|
|
215
|
+
`expiresAt`, …) can be overridden the same way.
|
|
216
|
+
|
|
217
|
+
```ts title="quickback/hooks/before-invitation-create.ts"
|
|
218
|
+
import { APIError } from "better-auth/api";
|
|
219
|
+
import { eq } from "drizzle-orm";
|
|
220
|
+
|
|
221
|
+
export default async ({ invitation, inviter, organization }, { authDb, authSchema }) => {
|
|
222
|
+
const [plan] = await authDb
|
|
223
|
+
.select({ policy: authSchema.organization.metadata })
|
|
224
|
+
.from(authSchema.organization)
|
|
225
|
+
.where(eq(authSchema.organization.id, organization.id))
|
|
226
|
+
.limit(1);
|
|
227
|
+
|
|
228
|
+
if (plan?.policy === "sandbox") {
|
|
229
|
+
throw new APIError("FORBIDDEN", { message: "Sandbox organizations cannot invite members." });
|
|
230
|
+
}
|
|
231
|
+
if (plan?.policy === "redirect") {
|
|
232
|
+
// Deliver every invite to the org owner instead of the typed address.
|
|
233
|
+
return { data: { email: inviter.email } };
|
|
234
|
+
}
|
|
235
|
+
};
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Notes:
|
|
239
|
+
|
|
240
|
+
- **Not a `databaseHook`.** It runs inside the organization plugin, before the
|
|
241
|
+
invitation row is written and before `sendInvitationEmail`. `ctx` is the
|
|
242
|
+
standard [hook ctx](#ctx-shape) minus `baContext`.
|
|
243
|
+
- **The seat cap runs first.** With the
|
|
244
|
+
[subscriptions plugin](/platform/auth/plugins/subscriptions), a full plan
|
|
245
|
+
refuses the invite before your hook is called.
|
|
246
|
+
- **`invitationLimit` is a config option, not a hook.** Better Auth's cap on
|
|
247
|
+
pending invitations per organization passes straight through
|
|
248
|
+
`plugins.organization` — see [Better Auth plugins](/configure/providers#better-auth-plugins).
|
|
249
|
+
- Requires the organization plugin; the file is a compile error without it.
|
|
250
|
+
|
|
204
251
|
## ctx shape
|
|
205
252
|
|
|
206
253
|
Every hook receives `(entity, ctx)`:
|
|
@@ -259,6 +306,7 @@ What happens when a hook throws is the #1 thing that bites people:
|
|
|
259
306
|
| `before-email-otp-activate` | The entire atomic ceremony rolls back: OTP consumption, hook writes, verification update, and session insert. |
|
|
260
307
|
| `after-user-create` | The user **is** created (the BA insert already committed). Any derived rows your hook started writing become orphans. |
|
|
261
308
|
| `after-session-create`| Same as above — the session row exists; partial writes leak. |
|
|
309
|
+
| `before-invitation-create` | The invitation is **not** created and no email is sent. Throw Better Auth's `APIError` for a clean 4xx. |
|
|
262
310
|
|
|
263
311
|
For `after-*` hooks, design for **idempotency**: use the entity's `id` as a stable seed for any derived rows so re-running the hook (manually or via a background reconciler) is safe. Don't generate fresh `cuid()`s for derived rows you'd want to recover.
|
|
264
312
|
|