@aphexcms/auth 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,227 @@
1
+ import type { BetterAuthOptions } from 'better-auth';
2
+ import type { TwoFactorOptions } from 'better-auth/plugins';
3
+ import type { BootstrapPolicy, CacheAdapter, DatabaseAdapter, EmailAdapter } from '@aphexcms/cms-core/server';
4
+ /**
5
+ * One transactional email the auth flows can send. Deliberately structural
6
+ * rather than a concrete class: apps render these with their own Svelte
7
+ * components and branding, so the package only needs the two things it
8
+ * actually calls.
9
+ */
10
+ export interface AuthEmailTemplate {
11
+ subject: string;
12
+ render: (userName: string, url: string) => Promise<{
13
+ html: string;
14
+ text: string;
15
+ }>;
16
+ }
17
+ /**
18
+ * Like `AuthEmailTemplate`, but the second argument is a short code the reader
19
+ * types back into a page rather than a link they click. Structurally identical,
20
+ * named apart so a template can't be wired into the wrong slot and silently mail
21
+ * a URL where a six-digit code belongs.
22
+ */
23
+ export interface AuthCodeEmailTemplate {
24
+ subject: string;
25
+ render: (userName: string, code: string) => Promise<{
26
+ html: string;
27
+ text: string;
28
+ }>;
29
+ }
30
+ /**
31
+ * Sender identity plus the templates the auth flows use. Mirrors the shape apps
32
+ * already export from `src/lib/server/email` — pass that object straight in.
33
+ */
34
+ export interface AuthEmailConfig {
35
+ from: string;
36
+ passwordReset: AuthEmailTemplate;
37
+ emailVerification: AuthEmailTemplate;
38
+ /**
39
+ * Branding for the second-factor code email. Optional — when omitted, a plain
40
+ * built-in template is used instead, so email 2FA works without writing one.
41
+ * Whether the feature is on at all is `options.twoFactorEmailOtp`, not this.
42
+ */
43
+ twoFactorOtp?: AuthCodeEmailTemplate;
44
+ }
45
+ /** Behavioural toggles an app owns, independent of the auth provider. */
46
+ export interface AuthOptions {
47
+ /**
48
+ * Require a verified email before sign-in. When on, a verification email is
49
+ * sent at sign-up and sign-in is blocked until the address is confirmed.
50
+ *
51
+ * Off by default so a fresh install works without an SMTP server. Turn it on
52
+ * in production — without it anyone can sign up with an address they don't
53
+ * own, and the first user becomes super admin.
54
+ *
55
+ * @default false
56
+ */
57
+ requireEmailVerification?: boolean;
58
+ /**
59
+ * Which second factors the sign-in challenge offers.
60
+ *
61
+ * - `'totp'` — a rotating code from an authenticator app.
62
+ * - `'email'` — a one-time code mailed on request. Needs an email adapter;
63
+ * without one it is dropped regardless, because a factor that can't be
64
+ * delivered locks people out of their own accounts. Branding is optional —
65
+ * supply `email.twoFactorOtp` or accept the plain built-in template.
66
+ *
67
+ * Backup codes are always available and aren't listed here: better-auth mints
68
+ * them when 2FA is enabled and they're the recovery path when every other
69
+ * factor is unreachable, so switching them off would only create lockouts.
70
+ *
71
+ * Dropping `'totp'` makes email the only factor, which also means enrolment
72
+ * no longer shows a QR code — users turn 2FA on and codes simply arrive.
73
+ * Convenient, and weaker: whoever holds the password and the inbox gets
74
+ * through, and password resets go to that same inbox.
75
+ *
76
+ * An empty array is treated as `['totp']` — zero factors would mean 2FA that
77
+ * can be enabled but never satisfied.
78
+ *
79
+ * @default ['totp', 'email']
80
+ */
81
+ twoFactorMethods?: Array<'totp' | 'email'>;
82
+ /**
83
+ * Let a signed-in user delete their own account, mounting better-auth's
84
+ * `/delete-user` endpoint. Deleting cascades into the CMS: the user's profile
85
+ * and memberships go, and a `user.deleted` event is emitted per organization
86
+ * so consumers can erase what the account left behind (the built-in one
87
+ * removes their avatar from object storage, not just its database row).
88
+ *
89
+ * Off by default because turning it on is a real change to the auth surface:
90
+ * account deletion becomes reachable over HTTP by anyone with a session, and
91
+ * it is irreversible. Turn it on when you need a right-to-erasure path —
92
+ * that's what it's for — and note that this package ships the endpoint, not
93
+ * the UI to call it.
94
+ *
95
+ * @default false
96
+ */
97
+ allowAccountDeletion?: boolean;
98
+ /**
99
+ * Restrict account creation to addresses holding a pending, unexpired
100
+ * invitation. Gates the sign-up *endpoint*, so a direct POST is rejected the
101
+ * same as a form submission.
102
+ *
103
+ * Note this is not better-auth's `disableSignUp`: an invitee has to create an
104
+ * account before they can accept an invitation, so disabling sign-up outright
105
+ * makes invitations impossible to accept.
106
+ *
107
+ * On by default, with one exception: sign-up is always allowed while the
108
+ * instance is provably empty, since nobody exists yet to send an invitation.
109
+ * So a fresh install is "first person to sign up owns it, and the door shuts
110
+ * behind them" — open exactly long enough to be claimed.
111
+ *
112
+ * That leaves one window: an instance reachable *before* you claim it belongs
113
+ * to whoever finds it first. Close it with a `bootstrap` recipe (`claimCode`,
114
+ * `allowlistEmail`) rather than by turning this off.
115
+ *
116
+ * @default true
117
+ */
118
+ inviteOnly?: boolean;
119
+ }
120
+ /**
121
+ * Everything `createAphexAuth` needs.
122
+ *
123
+ * Nothing here is read from the environment: a package can't use SvelteKit's
124
+ * `$env/dynamic/private`, and hiding env lookups inside a dependency makes
125
+ * misconfiguration hard to trace. The app reads its own env and passes values in.
126
+ */
127
+ export interface AphexAuthConfig {
128
+ /** The CMS database adapter — used to keep `cms_user_profiles` in sync. */
129
+ database: DatabaseAdapter;
130
+ /**
131
+ * The raw Drizzle client better-auth's own adapter writes through. Typed
132
+ * loosely on purpose: this is the one place a Postgres and a libsql Drizzle
133
+ * instance have to be interchangeable, and they share no common base type.
134
+ */
135
+ drizzleDb: unknown;
136
+ /** Which Drizzle dialect `drizzleDb` is. postgres/pglite → 'pg', libsql → 'sqlite'. */
137
+ dialect: 'pg' | 'sqlite';
138
+ /** Signing secret. Required at runtime; a placeholder is used while `building`. */
139
+ secret?: string;
140
+ /** Public origin, e.g. `https://cms.example.com`. Used for links in emails. */
141
+ baseURL?: string;
142
+ /**
143
+ * Origins allowed to make cross-origin auth requests. Without this, cookie-auth
144
+ * mutations are reachable from any site a signed-in admin visits. Defaults to
145
+ * `baseURL`.
146
+ */
147
+ trustedOrigins?: string[];
148
+ /** True during SvelteKit's build/analyse pass, when placeholders stand in for secrets. */
149
+ building?: boolean;
150
+ /** Transport for outbound mail. `null` disables password reset and verification emails. */
151
+ emailAdapter?: EmailAdapter | null;
152
+ /** Sender identity and templates. Omit alongside `emailAdapter` to disable email. */
153
+ email?: AuthEmailConfig | null;
154
+ /** Backs session-cookie caching and the verification-email throttle. */
155
+ cache?: CacheAdapter | null;
156
+ /** App-owned behavioural toggles. */
157
+ options?: AuthOptions;
158
+ /**
159
+ * How a fresh instance gets its first administrator.
160
+ *
161
+ * Defaults to `openFirstUser()`: the first person to sign up owns the
162
+ * instance, the same as WordPress, Ghost, Strapi, Payload and Dokploy. That
163
+ * assumes you sign up promptly after deploying — an instance left reachable
164
+ * beforehand belongs to whoever finds it.
165
+ *
166
+ * Harden it with `claimCode()`, which additionally requires a code printed to
167
+ * the server log at startup so being first to the URL isn't enough, or with
168
+ * `allowlistEmail()`; `never()` turns promotion off entirely.
169
+ *
170
+ * ```ts
171
+ * import { allowlistEmail } from '@aphexcms/auth';
172
+ * bootstrap: allowlistEmail(env.APHEX_BOOTSTRAP_EMAIL)
173
+ * ```
174
+ */
175
+ bootstrap?: BootstrapPolicy;
176
+ /**
177
+ * OAuth / social sign-in, passed straight through to better-auth. No schema
178
+ * change needed — provider links live in the existing `account` table.
179
+ *
180
+ * ```ts
181
+ * socialProviders: {
182
+ * google: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET }
183
+ * }
184
+ * ```
185
+ *
186
+ * Typed straight off better-auth rather than restated here, so provider names
187
+ * and their option shapes can't drift out of step with the installed version.
188
+ */
189
+ socialProviders?: BetterAuthOptions['socialProviders'];
190
+ /**
191
+ * Two-factor authentication via an authenticator app (TOTP), plus backup codes.
192
+ * Off unless set — `true` takes better-auth's defaults, an object configures it.
193
+ *
194
+ * The tables are in the schema either way, so turning this on is a config change
195
+ * rather than a migration.
196
+ *
197
+ * ```ts
198
+ * twoFactor: true
199
+ * twoFactor: { issuer: 'Acme CMS', totpOptions: { period: 30 } }
200
+ * ```
201
+ *
202
+ * Enrolling and verifying is driven from the client — add `twoFactorClient()` to
203
+ * your better-auth client and call `twoFactor.enable` / `verifyTotp`.
204
+ */
205
+ twoFactor?: boolean | TwoFactorOptions;
206
+ /**
207
+ * Shown as the issuer in authenticator apps when `twoFactor` is on, so make it
208
+ * something a user will recognise next to a 6-digit code. Defaults to
209
+ * better-auth's own fallback ("Better Auth") — override it.
210
+ */
211
+ appName?: string;
212
+ /**
213
+ * Full escape hatch. Receives the assembled better-auth options and returns
214
+ * what should actually be passed to `betterAuth()`.
215
+ *
216
+ * This exists so the wrapper never becomes a ceiling: better-auth is a peer
217
+ * dependency, so you choose its version, and any option it gains — new
218
+ * plugins, new providers — is reachable here without waiting on a release of
219
+ * this package.
220
+ *
221
+ * ```ts
222
+ * betterAuth: (base) => ({ ...base, plugins: [...base.plugins, twoFactor()] })
223
+ * ```
224
+ */
225
+ betterAuth?: (base: Record<string, unknown>) => Record<string, unknown>;
226
+ }
227
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EACX,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,MAAM,2BAA2B,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnF;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,iBAAiB,CAAC;IACjC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC3B;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gBAAgB,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,2EAA2E;IAC3E,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB,uFAAuF;IACvF,OAAO,EAAE,IAAI,GAAG,QAAQ,CAAC;IAEzB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEnC,qFAAqF;IACrF,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAE/B,wEAAwE;IACxE,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B,qCAAqC;IACrC,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IAEvD;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAEvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxE"}
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
package/package.json ADDED
@@ -0,0 +1,56 @@
1
+ {
2
+ "name": "@aphexcms/auth",
3
+ "version": "0.1.0",
4
+ "license": "MIT",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com/IcelandicIcecream/aphex.git",
11
+ "directory": "packages/auth"
12
+ },
13
+ "type": "module",
14
+ "main": "./dist/index.js",
15
+ "types": "./dist/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./schema/pg": {
23
+ "types": "./dist/schema/pg.d.ts",
24
+ "import": "./dist/schema/pg.js",
25
+ "default": "./dist/schema/pg.js"
26
+ },
27
+ "./schema/sqlite": {
28
+ "types": "./dist/schema/sqlite.d.ts",
29
+ "import": "./dist/schema/sqlite.js",
30
+ "default": "./dist/schema/sqlite.js"
31
+ }
32
+ },
33
+ "files": [
34
+ "dist"
35
+ ],
36
+ "dependencies": {
37
+ "@aphexcms/cms-core": "^9.8.1"
38
+ },
39
+ "peerDependencies": {
40
+ "@better-auth/api-key": "^1.6.25",
41
+ "better-auth": "^1.6.25",
42
+ "drizzle-orm": "^0.45.2",
43
+ "@aphexcms/cms-core": "^9.8.1"
44
+ },
45
+ "devDependencies": {
46
+ "@better-auth/api-key": "^1.6.25",
47
+ "better-auth": "^1.6.25",
48
+ "drizzle-orm": "^0.45.2",
49
+ "typescript": "^5.9.3",
50
+ "@aphexcms/cms-core": "^9.8.1"
51
+ },
52
+ "scripts": {
53
+ "build": "tsc",
54
+ "dev:local": "node ../../scripts/swap-package-paths.js ./package.json src"
55
+ }
56
+ }