@aphexcms/cms-core 9.8.1 → 9.9.0

package/dist/api/organizations.d.ts

@@ -65,7 +65,8 @@ export declare class OrganizationsApi {
         success: boolean;
     }>>;
     /**
-     * Delete an organization (super_admin only)
+     * Delete an organization, its media, and every membership in it. Owners only —
+     * enforced by the route, not here.
      */
     static remove(id: string): Promise<ApiResponse<{
         success: boolean;

package/dist/api/organizations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../src/lib/api/organizations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EACX,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AACnD,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AACnD,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACzD,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,IAAI,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC5B;;OAEG;WACU,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAIjE;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIxF;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAIhG;;OAEG;WACU,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIpE;;OAEG;WACU,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAY5D;;OAEG;WACU,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAIrE;;OAEG;WACU,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAI9F;;OAEG;WACU,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAIhG;;OAEG;WACU,gBAAgB,CAC5B,IAAI,EAAE,uBAAuB,GAC3B,OAAO,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAI3C;;OAEG;WACU,MAAM,CAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,yBAAyB,GAC7B,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIrC;;OAEG;WACU,gBAAgB,CAC5B,IAAI,EAAE,uBAAuB,GAC3B,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAI7C;;OAEG;WACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAG3E;AAGD,eAAO,MAAM,aAAa;;;;;;;;;;;;;CAazB,CAAC"}
+{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../src/lib/api/organizations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EACX,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AACnD,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AACnD,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACzD,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,IAAI,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC5B;;OAEG;WACU,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAIjE;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIxF;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAIhG;;OAEG;WACU,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIpE;;OAEG;WACU,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAY5D;;OAEG;WACU,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAIrE;;OAEG;WACU,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAI9F;;OAEG;WACU,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAIhG;;OAEG;WACU,gBAAgB,CAC5B,IAAI,EAAE,uBAAuB,GAC3B,OAAO,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAI3C;;OAEG;WACU,MAAM,CAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,yBAAyB,GAC7B,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAIrC;;OAEG;WACU,gBAAgB,CAC5B,IAAI,EAAE,uBAAuB,GAC3B,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAI7C;;;OAGG;WACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAG3E;AAGD,eAAO,MAAM,aAAa;;;;;;;;;;;;;CAazB,CAAC"}

package/dist/api/organizations.js

@@ -76,7 +76,8 @@ export class OrganizationsApi {
         return apiClient.delete('/organizations/invitations', data);
     }
     /**
-     * Delete an organization (super_admin only)
+     * Delete an organization, its media, and every membership in it. Owners only —
+     * enforced by the route, not here.
      */
     static async remove(id) {
         return apiClient.delete(`/organizations/${id}`);

package/dist/api/schemas/jobs.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/**
+ * Body for both operator actions on a job.
+ *
+ * `organizationId` exists solely for the instance-wide view: a super admin looking at every
+ * tenant's queue needs to act on a job that isn't in their *active* org, and the id alone
+ * doesn't say where it lives. Omit it and the action targets the caller's active organization
+ * — which is the only thing a non-super-admin may ever do (the route rejects a mismatch with
+ * 403 rather than trusting the body).
+ */
+export declare const jobActionRequestSchema: z.ZodObject<{
+    organizationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type JobActionRequest = z.infer<typeof jobActionRequestSchema>;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/api/schemas/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../src/lib/api/schemas/jobs.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/api/schemas/jobs.js

@@ -0,0 +1,17 @@
+// Request contracts for the job queue's operator actions (POST /api/jobs/:id/retry|cancel).
+// Single source of truth: the route validates with these, the client infers its input types
+// from them. The read endpoints (GET /jobs, /events, /jobs/health) keep their query schemas
+// in the route handler — per convention, GET-only shapes don't earn a shared module.
+import { z } from 'zod';
+/**
+ * Body for both operator actions on a job.
+ *
+ * `organizationId` exists solely for the instance-wide view: a super admin looking at every
+ * tenant's queue needs to act on a job that isn't in their *active* org, and the id alone
+ * doesn't say where it lives. Omit it and the action targets the caller's active organization
+ * — which is the only thing a non-super-admin may ever do (the route rejects a mismatch with
+ * 403 rather than trusting the body).
+ */
+export const jobActionRequestSchema = z.object({
+    organizationId: z.string().min(1).optional()
+});

package/dist/api/schemas/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/lib/api/schemas/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,iBAAiB;;;iBAO3B,CAAC;AAIJ,eAAO,MAAM,4BAA4B;;kBAI/B,CAAC;AAIX,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAIH,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAC;AAIH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AACxF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACtF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/lib/api/schemas/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,iBAAiB;;;iBAW3B,CAAC;AAIJ,eAAO,MAAM,4BAA4B;;kBAI/B,CAAC;AAIX,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAIH,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAC;AAIH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AACxF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACtF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/api/schemas/user.js

@@ -2,8 +2,12 @@ import { z } from 'zod';
 // ---------- PATCH /user ----------
 export const updateUserRequest = z
     .object({
-    name: z.string().min(1).optional(),
-    image: z.string().min(1).nullable().optional()
+    // Bounded so a display name can't be pasted in at essay length — it renders
+    // in sidebars, member lists, and audit trails that all assume it's short.
+    name: z.string().min(1).max(80).optional(),
+    // Generous, but finite: this holds a `/media/<id>/<filename>` path or an
+    // external provider's avatar URL, never free text.
+    image: z.string().min(1).max(2048).nullable().optional()
 })
     .refine((v) => v.name !== undefined || v.image !== undefined, {
     message: 'At least one field (name, image) is required'

package/dist/auth/account-deletion.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseAdapter } from '../db/interfaces/index.js';
+/**
+ * Thrown when an account may not be deleted yet. Providers translate it into their own
+ * transport error; the message is written to be shown to the user as-is.
+ */
+export declare class AccountDeletionBlockedError extends Error {
+    readonly code = "ACCOUNT_DELETION_BLOCKED";
+    constructor(message: string);
+}
+/**
+ * Throws unless this user can leave without stranding an organization.
+ *
+ * The rule is narrow on purpose: an organization whose only owner deletes their account has
+ * nobody left who can add members, change roles, or delete it — the org becomes unreachable
+ * to everyone including its remaining members, and no in-product path can recover it. Being
+ * the sole *member* is fine, because deleting the organization first is a thing the user can
+ * actually do; being the sole *owner* of an org with other people in it is the trap.
+ *
+ * Enforced server-side rather than in the confirmation dialog: the endpoint is reachable
+ * without the UI, and this is the check that decides whether an organization survives.
+ */
+export declare function assertAccountDeletable(db: DatabaseAdapter, userId: string): Promise<void>;
+/**
+ * Detach a deleted user from every organization.
+ *
+ * `cms_organization_members.user_id` has no foreign key to the profile table — memberships
+ * reference the auth layer's user, which cms-core doesn't own — so nothing cascades and a
+ * deleted account would otherwise keep appearing in member lists indefinitely, still holding
+ * whatever role it had.
+ *
+ * Call inside the same transaction as the profile delete, after the erasure events are
+ * emitted (those read the memberships to know which organizations to fan out to).
+ */
+export declare function detachUserFromOrganizations(tx: DatabaseAdapter, userId: string, organizationIds: readonly string[]): Promise<void>;
+//# sourceMappingURL=account-deletion.d.ts.map

package/dist/auth/account-deletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-deletion.d.ts","sourceRoot":"","sources":["../../src/lib/auth/account-deletion.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,8BAA8B;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAChD,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,SAAS,MAAM,EAAE,GAChC,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/auth/account-deletion.js

@@ -0,0 +1,65 @@
+// What has to be true before an account may be deleted, and what has to happen after.
+//
+// Lives in cms-core rather than in `@aphexcms/auth` for the same reason the sign-up gate
+// does: "can this account go?" is a CMS question about organizations and ownership, and it
+// must mean the same thing whichever provider authenticated the user. A provider supplies
+// the lifecycle hook; it doesn't get to re-derive the rule.
+import { cmsLogger } from '../utils/logger.js';
+/**
+ * Thrown when an account may not be deleted yet. Providers translate it into their own
+ * transport error; the message is written to be shown to the user as-is.
+ */
+export class AccountDeletionBlockedError extends Error {
+    code = 'ACCOUNT_DELETION_BLOCKED';
+    constructor(message) {
+        super(message);
+        this.name = 'AccountDeletionBlockedError';
+    }
+}
+/**
+ * Throws unless this user can leave without stranding an organization.
+ *
+ * The rule is narrow on purpose: an organization whose only owner deletes their account has
+ * nobody left who can add members, change roles, or delete it — the org becomes unreachable
+ * to everyone including its remaining members, and no in-product path can recover it. Being
+ * the sole *member* is fine, because deleting the organization first is a thing the user can
+ * actually do; being the sole *owner* of an org with other people in it is the trap.
+ *
+ * Enforced server-side rather than in the confirmation dialog: the endpoint is reachable
+ * without the UI, and this is the check that decides whether an organization survives.
+ */
+export async function assertAccountDeletable(db, userId) {
+    const memberships = await db.findUserOrganizations(userId);
+    const stranded = [];
+    for (const { organization } of memberships) {
+        const members = await db.findOrganizationMembers(organization.id);
+        const owners = members.filter((m) => m.role === 'owner');
+        // Sole owner, and somebody else is still here.
+        if (owners.length === 1 && owners[0]?.userId === userId && members.length > 1) {
+            stranded.push(organization.name);
+        }
+    }
+    if (stranded.length > 0) {
+        throw new AccountDeletionBlockedError(`You are the only owner of ${stranded.join(', ')}. Transfer ownership or remove the other ` +
+            `members before deleting your account.`);
+    }
+}
+/**
+ * Detach a deleted user from every organization.
+ *
+ * `cms_organization_members.user_id` has no foreign key to the profile table — memberships
+ * reference the auth layer's user, which cms-core doesn't own — so nothing cascades and a
+ * deleted account would otherwise keep appearing in member lists indefinitely, still holding
+ * whatever role it had.
+ *
+ * Call inside the same transaction as the profile delete, after the erasure events are
+ * emitted (those read the memberships to know which organizations to fan out to).
+ */
+export async function detachUserFromOrganizations(tx, userId, organizationIds) {
+    for (const organizationId of organizationIds) {
+        const removed = await tx.removeMember(organizationId, userId);
+        if (!removed) {
+            cmsLogger.warn('[AccountDeletion]', `No membership row for ${userId} in ${organizationId} — nothing to detach.`);
+        }
+    }
+}

package/dist/auth/bootstrap.d.ts

@@ -0,0 +1,104 @@
+import type { DatabaseAdapter } from '../db/interfaces/index.js';
+/** Instance-level role a bootstrap policy may grant. */
+export type InstanceRole = 'super_admin' | 'admin' | 'editor' | 'viewer';
+export interface BootstrapContext {
+    user: {
+        id: string;
+        email: string;
+        emailVerified: boolean;
+    };
+    /**
+     * True only when the system is *provably* empty.
+     *
+     * Never inferred from a missing capability: an adapter that can't answer the
+     * question yields `false`, so an unanswerable check can't be mistaken for
+     * "nobody is here yet, promote this person".
+     */
+    isFirstUser: boolean;
+    /** The request that triggered profile creation, when there is one. */
+    request?: Request;
+    db: DatabaseAdapter;
+}
+/**
+ * Decides what instance role a brand-new user profile gets.
+ *
+ * Bootstrapping is a policy decision, not a library one — how you claim a fresh
+ * instance depends on how you deploy it. Return `null` for "no promotion"; the
+ * caller falls back to the ordinary `editor` role.
+ */
+export interface BootstrapPolicy {
+    (ctx: BootstrapContext): Promise<InstanceRole | null>;
+    /**
+     * Optional one-off startup step, run before any request is served.
+     *
+     * Lets a recipe own its own setup instead of making the app wire it: only
+     * `claimCode()` needs one (to generate and log its code), and an app that
+     * swaps recipes shouldn't have to remember to delete a hook. Callers invoke
+     * it as `policy.prepare?.(db)` — recipes without setup simply omit it.
+     */
+    prepare?: (db: DatabaseAdapter) => Promise<void>;
+}
+/**
+ * Ensure an unclaimed instance has a pending claim code, and log it.
+ *
+ * Only the **hash** is persisted: a leaked database dump or backup shouldn't be
+ * enough to claim the instance. Called at startup by `claimCode()` consumers.
+ */
+export declare function ensureClaimCode(db: DatabaseAdapter): Promise<void>;
+/**
+ * True when nobody has claimed this instance yet and a code is waiting to be
+ * used. Drives the sign-up form's claim-code field: without this the code has
+ * nowhere to go but a hand-set cookie, which is not a flow anyone can follow.
+ *
+ * Deliberately narrow. It reveals only that an instance is unclaimed — never the
+ * code or its hash — so it is safe to hand to an unauthenticated page. That fact
+ * is already obvious to anyone who can reach a CMS with no users in it.
+ */
+export declare function isInstanceUnclaimed(db: DatabaseAdapter): Promise<boolean>;
+/**
+ * The default. Keeps the familiar first-run wizard, but promotion requires a
+ * code printed to the server log at startup — so arriving first isn't enough,
+ * you also have to control the deployment. Same shape as Jupyter's `?token=`
+ * and GitLab's generated root password.
+ *
+ * Clearing the hash here is not what makes the code single-use — two concurrent
+ * claims can both read it before either clears it. Mutual exclusion comes from
+ * `tryClaimBootstrap`, which `createUserProfileWithBootstrap` takes before
+ * granting any instance role: the loser is demoted to an ordinary profile even
+ * though this returned `super_admin`. Clearing the hash still matters, just for
+ * the sequential case — it stops the code being reused later.
+ *
+ * One residual: a claim can be spent by a request whose profile insert then
+ * fails, which costs a code rather than granting anything. Recover by clearing
+ * the key from instance settings and restarting for a fresh one.
+ */
+export declare function claimCode(options?: {
+    readCode?: (request?: Request) => string | undefined;
+}): BootstrapPolicy;
+/**
+ * First user whose address is on the allowlist becomes super admin — Discourse's
+ * `DISCOURSE_DEVELOPER_EMAILS`. Good when you know the owner's address at deploy
+ * time and would rather not read logs.
+ *
+ * This recipe is only as strong as the address is trustworthy, so pair it with
+ * `requireEmailVerification`. That's enforced at the auth layer — better-auth
+ * refuses to complete sign-in for an unconfirmed address, so an unverified user
+ * never reaches profile creation at all. Re-checking it here would be dead code
+ * when verification is on, and would brick a fresh install when it's off.
+ */
+export declare function allowlistEmail(emails: string | readonly string[] | undefined): BootstrapPolicy;
+/**
+ * Whoever signs up first becomes super admin, with nothing else required.
+ *
+ * This is what WordPress, Ghost, Strapi and Payload do, and it's fine when you
+ * install immediately after deploying. It is **not** fine for an instance that
+ * sits reachable before anyone signs in: the first stranger to find the URL owns
+ * it. Opt in deliberately.
+ */
+export declare function openFirstUser(): BootstrapPolicy;
+/**
+ * Never promote anyone. Provision the first administrator out of band — a seed
+ * script, a migration, or a direct row — the way Directus and Keycloak do.
+ */
+export declare function never(): BootstrapPolicy;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/auth/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/lib/auth/bootstrap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAKzE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5D;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,eAAe,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACtD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAcD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAK/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACxB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;CAAO,GACpE,eAAe,CAqDjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,eAAe,CAsB9F;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED;;;GAGG;AACH,wBAAgB,KAAK,IAAI,eAAe,CAEvC"}

package/dist/auth/bootstrap.js

@@ -0,0 +1,164 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { cmsLogger } from '../utils/logger.js';
+import { isInstanceEmpty } from './instance-state.js';
+/** Where the claim-code hash lives inside the instance-settings blob. */
+const CLAIM_CODE_KEY = 'bootstrapClaimCodeHash';
+function hashCode(code) {
+    return createHash('sha256').update(code).digest('hex');
+}
+/** Constant-time compare of two hex digests of equal length. */
+function digestsMatch(a, b) {
+    const left = Buffer.from(a, 'hex');
+    const right = Buffer.from(b, 'hex');
+    if (left.length !== right.length || left.length === 0)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * Ensure an unclaimed instance has a pending claim code, and log it.
+ *
+ * Only the **hash** is persisted: a leaked database dump or backup shouldn't be
+ * enough to claim the instance. Called at startup by `claimCode()` consumers.
+ */
+export async function ensureClaimCode(db) {
+    if (!(await isInstanceEmpty(db)))
+        return;
+    const settings = await db.getInstanceSettings();
+    if (typeof settings[CLAIM_CODE_KEY] === 'string')
+        return;
+    const code = randomBytes(24).toString('base64url');
+    await db.updateInstanceSettings({ [CLAIM_CODE_KEY]: hashCode(code) });
+    cmsLogger.info('[Bootstrap]', `\n\n  This instance has no administrator yet.\n` +
+        `  Sign up at /admin and enter this claim code to become the super admin:\n\n` +
+        `      ${code}\n\n` +
+        `  It is single-use and is not stored in recoverable form. If you lose it,\n` +
+        `  clear "${CLAIM_CODE_KEY}" from instance settings and restart to get a new one.\n`);
+}
+/**
+ * True when nobody has claimed this instance yet and a code is waiting to be
+ * used. Drives the sign-up form's claim-code field: without this the code has
+ * nowhere to go but a hand-set cookie, which is not a flow anyone can follow.
+ *
+ * Deliberately narrow. It reveals only that an instance is unclaimed — never the
+ * code or its hash — so it is safe to hand to an unauthenticated page. That fact
+ * is already obvious to anyone who can reach a CMS with no users in it.
+ */
+export async function isInstanceUnclaimed(db) {
+    if (!(await isInstanceEmpty(db)))
+        return false;
+    const settings = await db.getInstanceSettings();
+    return typeof settings[CLAIM_CODE_KEY] === 'string';
+}
+/**
+ * The default. Keeps the familiar first-run wizard, but promotion requires a
+ * code printed to the server log at startup — so arriving first isn't enough,
+ * you also have to control the deployment. Same shape as Jupyter's `?token=`
+ * and GitLab's generated root password.
+ *
+ * Clearing the hash here is not what makes the code single-use — two concurrent
+ * claims can both read it before either clears it. Mutual exclusion comes from
+ * `tryClaimBootstrap`, which `createUserProfileWithBootstrap` takes before
+ * granting any instance role: the loser is demoted to an ordinary profile even
+ * though this returned `super_admin`. Clearing the hash still matters, just for
+ * the sequential case — it stops the code being reused later.
+ *
+ * One residual: a claim can be spent by a request whose profile insert then
+ * fails, which costs a code rather than granting anything. Recover by clearing
+ * the key from instance settings and restarting for a fresh one.
+ */
+export function claimCode(options = {}) {
+    /**
+     * Header first, then an `aphex_bootstrap_code` cookie. The profile is created
+     * on the first authenticated request after sign-up, which may be a redirect
+     * the signup form doesn't control, so a header alone would be unreachable from
+     * a plain HTML flow. Override `readCode` to accept it somewhere else.
+     *
+     * Deliberately *not* a `?claim=` query parameter, which this used to accept.
+     * A URL carrying the code lands in browser history, server and proxy access
+     * logs, and any `Referer` sent to a third party — persisting a credential in
+     * several places nobody thinks to clear, to save one hop that the cookie
+     * already covers.
+     */
+    const readCode = options.readCode ??
+        ((request) => {
+            if (!request)
+                return undefined;
+            const header = request.headers.get('x-aphex-bootstrap-code');
+            if (header)
+                return header;
+            const cookie = request.headers.get('cookie');
+            const raw = cookie?.match(/(?:^|;\s*)aphex_bootstrap_code=([^;]+)/)?.[1];
+            // The sign-up form percent-encodes the value. A generated base64url code
+            // has nothing to decode, but a custom one may.
+            return raw === undefined ? undefined : decodeURIComponent(raw);
+        });
+    const policy = async ({ isFirstUser, request, db }) => {
+        if (!isFirstUser)
+            return null;
+        const supplied = readCode(request)?.trim();
+        if (!supplied)
+            return null;
+        const settings = await db.getInstanceSettings();
+        const expected = settings[CLAIM_CODE_KEY];
+        if (typeof expected !== 'string')
+            return null;
+        if (!digestsMatch(hashCode(supplied), expected)) {
+            cmsLogger.warn('[Bootstrap]', 'Rejected claim attempt — code did not match');
+            return null;
+        }
+        // Single-use: clearing the hash is what makes a second claimant lose.
+        await db.updateInstanceSettings({ [CLAIM_CODE_KEY]: null });
+        cmsLogger.info('[Bootstrap]', 'Instance claimed — super admin created');
+        return 'super_admin';
+    };
+    // The code only exists because this recipe was chosen, so this recipe is what
+    // generates it. Swapping to another recipe takes the startup step with it.
+    policy.prepare = ensureClaimCode;
+    return policy;
+}
+/**
+ * First user whose address is on the allowlist becomes super admin — Discourse's
+ * `DISCOURSE_DEVELOPER_EMAILS`. Good when you know the owner's address at deploy
+ * time and would rather not read logs.
+ *
+ * This recipe is only as strong as the address is trustworthy, so pair it with
+ * `requireEmailVerification`. That's enforced at the auth layer — better-auth
+ * refuses to complete sign-in for an unconfirmed address, so an unverified user
+ * never reaches profile creation at all. Re-checking it here would be dead code
+ * when verification is on, and would brick a fresh install when it's off.
+ */
+export function allowlistEmail(emails) {
+    const allowed = new Set((typeof emails === 'string' ? emails.split(',') : (emails ?? []))
+        .map((email) => email.trim().toLowerCase())
+        .filter(Boolean));
+    return async ({ isFirstUser, user }) => {
+        if (!isFirstUser || allowed.size === 0)
+            return null;
+        if (!allowed.has(user.email.trim().toLowerCase()))
+            return null;
+        if (!user.emailVerified) {
+            // Advice, not enforcement — the decision belongs to the auth layer.
+            cmsLogger.warn('[Bootstrap]', `Promoting ${user.email} on an unverified address. Set ` +
+                `AUTH_REQUIRE_EMAIL_VERIFICATION=true so the address has to be proven.`);
+        }
+        return 'super_admin';
+    };
+}
+/**
+ * Whoever signs up first becomes super admin, with nothing else required.
+ *
+ * This is what WordPress, Ghost, Strapi and Payload do, and it's fine when you
+ * install immediately after deploying. It is **not** fine for an instance that
+ * sits reachable before anyone signs in: the first stranger to find the URL owns
+ * it. Opt in deliberately.
+ */
+export function openFirstUser() {
+    return async ({ isFirstUser }) => (isFirstUser ? 'super_admin' : null);
+}
+/**
+ * Never promote anyone. Provision the first administrator out of band — a seed
+ * script, a migration, or a direct row — the way Directus and Keycloak do.
+ */
+export function never() {
+    return async () => null;
+}

package/dist/auth/instance-state.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseAdapter } from '../db/interfaces/index.js';
+/**
+ * True only when the instance is *provably* empty — the adapter can answer the
+ * question, and the answer is "no user profiles exist".
+ *
+ * Returns `false` when the adapter doesn't implement `hasAnyUserProfiles()`,
+ * which is the safe direction: bootstrap promotion is skipped and the invite
+ * gate stays shut rather than swinging open.
+ */
+export declare function isInstanceEmpty(db: DatabaseAdapter): Promise<boolean>;
+/** Whether the adapter can answer `isInstanceEmpty` at all — for warning about a skipped bootstrap. */
+export declare function canDetermineInstanceEmptiness(db: DatabaseAdapter): boolean;
+//# sourceMappingURL=instance-state.d.ts.map

package/dist/auth/instance-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-state.d.ts","sourceRoot":"","sources":["../../src/lib/auth/instance-state.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3E;AAED,uGAAuG;AACvG,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAE1E"}

package/dist/auth/instance-state.js

@@ -0,0 +1,30 @@
+// The single definition of "has this instance been claimed yet?".
+//
+// Two features hang off this one fact — the bootstrap policy (who gets promoted
+// to super admin) and the invite gate (who may sign up at all) — and they must
+// agree, or the disagreement is a bypass rather than a bug.
+//
+// It also has one non-obvious rule that every caller has to get right, which is
+// why it lives in one place instead of six: **proof of emptiness, never absence
+// of proof.** `hasAnyUserProfiles` is optional on the adapter interface, and an
+// adapter that cannot answer must NOT be read as "nobody is here yet". Getting
+// that backwards is exactly how a missing implementation once promoted every
+// single sign-up to super admin.
+/**
+ * True only when the instance is *provably* empty — the adapter can answer the
+ * question, and the answer is "no user profiles exist".
+ *
+ * Returns `false` when the adapter doesn't implement `hasAnyUserProfiles()`,
+ * which is the safe direction: bootstrap promotion is skipped and the invite
+ * gate stays shut rather than swinging open.
+ */
+export async function isInstanceEmpty(db) {
+    const countUsers = db.hasAnyUserProfiles?.bind(db);
+    if (!countUsers)
+        return false;
+    return !(await countUsers());
+}
+/** Whether the adapter can answer `isInstanceEmpty` at all — for warning about a skipped bootstrap. */
+export function canDetermineInstanceEmptiness(db) {
+    return typeof db.hasAnyUserProfiles === 'function';
+}

package/dist/auth/invitation-status.d.ts

@@ -0,0 +1,25 @@
+import type { Invitation } from '../types/organization.js';
+/** The minimum shape these predicates need — so callers can pass rows from any layer. */
+export type InvitationState = Pick<Invitation, 'expiresAt' | 'acceptedAt'>;
+/** Default lifetime for a new invitation. */
+export declare const INVITATION_TTL_MS: number;
+/** When a freshly-created invitation should expire. */
+export declare function invitationExpiryFrom(now?: Date): Date;
+export declare function isAccepted(invitation: InvitationState): boolean;
+export declare function isExpired(invitation: InvitationState, now?: Date): boolean;
+/**
+ * Redeemable right now: not yet accepted and not yet expired.
+ *
+ * The only question worth asking in most places — whether a sign-up may proceed,
+ * whether to show it in the members list, whether a re-invite is redundant.
+ */
+export declare function isPendingInvitation(invitation: InvitationState, now?: Date): boolean;
+/**
+ * Lapsed without being used, so it is safe to clear and replace.
+ *
+ * Deliberately distinct from `!isPendingInvitation(...)`: an *accepted*
+ * invitation is also "not pending", but deleting it would erase the record that
+ * someone joined by invitation.
+ */
+export declare function isStaleInvitation(invitation: InvitationState, now?: Date): boolean;
+//# sourceMappingURL=invitation-status.d.ts.map

package/dist/auth/invitation-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitation-status.d.ts","sourceRoot":"","sources":["../../src/lib/auth/invitation-status.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC;AAE3E,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB,QAA0B,CAAC;AAEzD,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,IAAiB,GAAG,IAAI,CAEjE;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAE/D;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAE9F"}

package/dist/auth/invitation-status.js

@@ -0,0 +1,41 @@
+// The single definition of what an invitation's state means.
+//
+// This exists because three call sites independently decided what "pending"
+// meant and two of them drifted: the sign-up gate required unaccepted *and*
+// unexpired, the members list did the same, but the re-invite check tested only
+// `acceptedAt === null`. An expired invitation therefore blocked re-inviting
+// while being unusable and invisible — a permanent deadlock for that address.
+//
+// Anything that asks a question about invitation state imports from here. If a
+// rule changes (grace periods, revocation, resend windows), it changes once.
+/** Default lifetime for a new invitation. */
+export const INVITATION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** When a freshly-created invitation should expire. */
+export function invitationExpiryFrom(now = new Date()) {
+    return new Date(now.getTime() + INVITATION_TTL_MS);
+}
+export function isAccepted(invitation) {
+    return invitation.acceptedAt !== null;
+}
+export function isExpired(invitation, now = new Date()) {
+    return new Date(invitation.expiresAt).getTime() <= now.getTime();
+}
+/**
+ * Redeemable right now: not yet accepted and not yet expired.
+ *
+ * The only question worth asking in most places — whether a sign-up may proceed,
+ * whether to show it in the members list, whether a re-invite is redundant.
+ */
+export function isPendingInvitation(invitation, now = new Date()) {
+    return !isAccepted(invitation) && !isExpired(invitation, now);
+}
+/**
+ * Lapsed without being used, so it is safe to clear and replace.
+ *
+ * Deliberately distinct from `!isPendingInvitation(...)`: an *accepted*
+ * invitation is also "not pending", but deleting it would erase the record that
+ * someone joined by invitation.
+ */
+export function isStaleInvitation(invitation, now = new Date()) {
+    return !isAccepted(invitation) && isExpired(invitation, now);
+}