founder-schema 0.3.0 → 0.4.0

package/README.md

@@ -57,7 +57,7 @@ until it is on npm.
 The backend validates a request and the web client validates a form with the
 SAME schema object, so the two can never disagree about what is allowed.
 
-- **Every limit has a name** (`src/limits.ts`: `DISPLAY_NAME_MAX`,
+- **Every limit has a name** (`src/core/limits.ts`: `DISPLAY_NAME_MAX`,
   `LINK_URL_MAX`, `UPLOAD_MAX_BYTES`...). A schema uses the constant; a consumer
   imports the same constant for its counters or its Mongoose `maxlength`. Nobody
   types the digits again. Three copies of one number is how image alt text came
@@ -152,24 +152,27 @@ Two things that follow from it:
 
 ```
 src/
-  limits.ts              every length, size and count limit, by name (imports nothing)
-  validation.ts          message keys, the wire shape of an issue, toValidationIssues
-  errors.ts              every API error code (API_ERROR_CODE_VALUES)
-  uploads.ts             the upload key, its extensions and content types, presign
-  common.ts              usernames (and the reserved list), the enums, URLs, phone,
-                         location, coordinates, pagination
-  founder-profile.ts     the profile, links, venture, the card, the write bodies
-  onboarding.ts          the steps, their per-step schemas, the draft and the finish
-  feed.ts                posts, polls, comments, reactions, reports, params, pages
-  discover.ts            the Discover query, its page and its facets
-  chat.ts                config, token, opening a conversation, participants
-  responses/common.ts    success / error / paginated / { id } envelopes
-  index.ts               the public surface. Everything a consumer imports.
+  index.ts                 the public surface. Everything a consumer imports.
+  env.ts                   env field builders, its own entry: `founder-schema/env`
+  core/                    what every domain builds on (imports no domain)
+    limits.ts              every length, size and count limit, by name (imports nothing)
+    validation.ts          message keys, the wire shape of an issue, toValidationIssues
+    errors.ts              every API error code (API_ERROR_CODE_VALUES)
+    common.ts              usernames (and the reserved list), the enums, URLs, phone,
+                           location, coordinates, pagination
+    responses.ts           success / error / paginated / { id } envelopes
+  access/                  who may do what (CASL's words, shared by server and web)
+    roles.ts               the roles, who may grant which, the active-role window
+    permissions.ts         actions, subjects, the fields a rule may name, AppAbility
+    access.ts              GET /me/access, switching role, the MPIN
+  domains/<domain>/        one folder per product area: its bodies, params and answers
+    account/ audit/ chat/ discover/ feed/ onboarding/ profile/ team/ uploads/
 tests/
   ssot.test.ts           derived not copied, no body coercion, URLs, uploads, codes
   validation.test.ts     keys not sentences, no input leaves, limits applied
   onboarding-steps.test.ts  steps, step schemas and the finish body agree
   responses.test.ts      the envelopes, pinned
+  access.test.ts         roles, the grant table, the MPIN, rules across the wire
   public-surface.test.ts export-removal tripwire + the values the database is pinned to
 ```
 
@@ -252,7 +255,7 @@ bearing, so append at the end and never insert.
 ## Settled since the scaffold
 
 - **The npm name and the first publish:** `founder-schema`, 0.1.0, by the user.
-- **The onboarding steps:** seven, ruled 2026-09-22; see `src/onboarding.ts`.
+- **The onboarding steps:** seven, ruled 2026-09-22; see `src/domains/onboarding/onboarding.ts`.
 
 ## Contract decisions, 2026-09-21
 

package/dist/access/access.d.ts

@@ -0,0 +1,76 @@
+/**
+ * founder-schema: the access API
+ *
+ *   GET  /api/v1/me/access        who I am acting as, what I hold, my rules
+ *   PUT  /api/v1/me/active-role   switch role (a staff role needs the MPIN)
+ *   POST /api/v1/me/mpin          set the MPIN, once
+ *   PUT  /api/v1/me/mpin          change it, with the current one
+ *
+ * THE MPIN is a 6-digit code that stands between a signed-in member and their
+ * staff roles. Signing in proves who you are; the MPIN proves it is still you
+ * at the moment you pick up admin powers, on a phone that may have been left
+ * unlocked. Set once by its owner; a forgotten one is cleared by a superadmin
+ * (an audited action), after which the owner sets a new one. `MPIN_MAX_ATTEMPTS`
+ * wrong tries lock it for `MPIN_LOCK_MS`.
+ *
+ * THE ACTIVE ROLE is per account (the user's ruling, 2026-10-05): switching on
+ * one device switches every device. It lasts `ACTIVE_ROLE_TTL_MS`, and the
+ * server re-checks it on EVERY request: a role that was revoked, or that
+ * expired, is acting as a member again at once, not at the next sign-in.
+ *
+ * @module founder-schema/access/access
+ */
+import { z } from 'zod';
+export declare const MPIN_LENGTH = 6;
+/** Wrong tries before the MPIN locks. */
+export declare const MPIN_MAX_ATTEMPTS = 5;
+/** How long a locked MPIN stays locked. */
+export declare const MPIN_LOCK_MS: number;
+export declare const mpinSchema: z.ZodString;
+/** The answer to `GET /me/access`, and to every switch. */
+export declare const meAccessResponseSchema: z.ZodObject<{
+    roles: z.ZodArray<z.ZodEnum<{
+        superadmin: "superadmin";
+        manager: "manager";
+        moderator: "moderator";
+        support_agent: "support_agent";
+        member: "member";
+    }>>;
+    activeRole: z.ZodEnum<{
+        superadmin: "superadmin";
+        manager: "manager";
+        moderator: "moderator";
+        support_agent: "support_agent";
+        member: "member";
+    }>;
+    activeRoleExpiresAt: z.ZodNullable<z.ZodISODateTime>;
+    mpinSet: z.ZodBoolean;
+    rules: z.ZodArray<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+export type MeAccessResponse = z.infer<typeof meAccessResponseSchema>;
+/** `PUT /me/active-role`. Back to member needs nothing; any staff role needs the MPIN. */
+export declare const switchRoleBodySchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        superadmin: "superadmin";
+        manager: "manager";
+        moderator: "moderator";
+        support_agent: "support_agent";
+        member: "member";
+    }>;
+    mpin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SwitchRoleBody = z.infer<typeof switchRoleBodySchema>;
+/** `POST /me/mpin`: the first MPIN, typed twice. */
+export declare const setMpinBodySchema: z.ZodObject<{
+    mpin: z.ZodString;
+    confirmMpin: z.ZodString;
+}, z.core.$strip>;
+export type SetMpinBody = z.infer<typeof setMpinBodySchema>;
+/** `PUT /me/mpin`: the current MPIN, then the new one typed twice. */
+export declare const changeMpinBodySchema: z.ZodObject<{
+    currentMpin: z.ZodString;
+    mpin: z.ZodString;
+    confirmMpin: z.ZodString;
+}, z.core.$strip>;
+export type ChangeMpinBody = z.infer<typeof changeMpinBodySchema>;
+//# sourceMappingURL=access.d.ts.map

package/dist/access/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/access/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,2CAA2C;AAC3C,eAAO,MAAM,YAAY,QAAiB,CAAC;AAE3C,eAAO,MAAM,UAAU,aAA8D,CAAC;AAEtF,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;iBAWjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB;;;;;;;;;iBAQ7B,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,oDAAoD;AACpD,eAAO,MAAM,iBAAiB;;;iBAEA,CAAC;AAC/B,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,sEAAsE;AACtE,eAAO,MAAM,oBAAoB;;;;iBAEH,CAAC;AAC/B,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/access/access.js

@@ -0,0 +1,66 @@
+/**
+ * founder-schema: the access API
+ *
+ *   GET  /api/v1/me/access        who I am acting as, what I hold, my rules
+ *   PUT  /api/v1/me/active-role   switch role (a staff role needs the MPIN)
+ *   POST /api/v1/me/mpin          set the MPIN, once
+ *   PUT  /api/v1/me/mpin          change it, with the current one
+ *
+ * THE MPIN is a 6-digit code that stands between a signed-in member and their
+ * staff roles. Signing in proves who you are; the MPIN proves it is still you
+ * at the moment you pick up admin powers, on a phone that may have been left
+ * unlocked. Set once by its owner; a forgotten one is cleared by a superadmin
+ * (an audited action), after which the owner sets a new one. `MPIN_MAX_ATTEMPTS`
+ * wrong tries lock it for `MPIN_LOCK_MS`.
+ *
+ * THE ACTIVE ROLE is per account (the user's ruling, 2026-10-05): switching on
+ * one device switches every device. It lasts `ACTIVE_ROLE_TTL_MS`, and the
+ * server re-checks it on EVERY request: a role that was revoked, or that
+ * expired, is acting as a member again at once, not at the next sign-in.
+ *
+ * @module founder-schema/access/access
+ */
+import { z } from 'zod';
+import { VALIDATION_MESSAGE } from '../core/validation.js';
+import { packedRulesSchema } from './permissions.js';
+import { MEMBER_ROLE, roleSchema } from './roles.js';
+export const MPIN_LENGTH = 6;
+/** Wrong tries before the MPIN locks. */
+export const MPIN_MAX_ATTEMPTS = 5;
+/** How long a locked MPIN stays locked. */
+export const MPIN_LOCK_MS = 15 * 60 * 1000;
+export const mpinSchema = z.string().regex(/^\d{6}$/, VALIDATION_MESSAGE.mpinInvalid);
+/** The answer to `GET /me/access`, and to every switch. */
+export const meAccessResponseSchema = z.object({
+    /** Every role held, member always among them, highest first. */
+    roles: z.array(roleSchema).min(1),
+    /** The role being acted as now. Member when no staff role is switched on. */
+    activeRole: roleSchema,
+    /** When the active staff role lapses back to member. Null while acting as a member. */
+    activeRoleExpiresAt: z.iso.datetime().nullable(),
+    /** Whether an MPIN is set, so the switcher knows to ask for one or to offer setting one. */
+    mpinSet: z.boolean(),
+    /** The active role's permissions, packed (`packRules`). */
+    rules: packedRulesSchema,
+});
+/** `PUT /me/active-role`. Back to member needs nothing; any staff role needs the MPIN. */
+export const switchRoleBodySchema = z
+    .object({
+    role: roleSchema,
+    mpin: mpinSchema.optional(),
+})
+    .refine((body) => body.role === MEMBER_ROLE || body.mpin !== undefined, {
+    path: ['mpin'],
+    error: VALIDATION_MESSAGE.mpinRequired,
+});
+const confirmed = (body) => body.mpin === body.confirmMpin;
+const mismatch = { path: ['confirmMpin'], error: VALIDATION_MESSAGE.mpinMismatch };
+/** `POST /me/mpin`: the first MPIN, typed twice. */
+export const setMpinBodySchema = z
+    .object({ mpin: mpinSchema, confirmMpin: mpinSchema })
+    .refine(confirmed, mismatch);
+/** `PUT /me/mpin`: the current MPIN, then the new one typed twice. */
+export const changeMpinBodySchema = z
+    .object({ currentMpin: mpinSchema, mpin: mpinSchema, confirmMpin: mpinSchema })
+    .refine(confirmed, mismatch);
+//# sourceMappingURL=access.js.map

package/dist/access/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../../src/access/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,yCAAyC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;AAEtF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,gEAAgE;IAChE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,6EAA6E;IAC7E,UAAU,EAAE,UAAU;IACtB,uFAAuF;IACvF,mBAAmB,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAChD,4FAA4F;IAC5F,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,2DAA2D;IAC3D,KAAK,EAAE,iBAAiB;CACzB,CAAC,CAAC;AAGH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE;CAC5B,CAAC;KACD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE;IACtE,IAAI,EAAE,CAAC,MAAM,CAAC;IACd,KAAK,EAAE,kBAAkB,CAAC,YAAY;CACvC,CAAC,CAAC;AAGL,MAAM,SAAS,GAAG,CAAkD,IAAO,EAAE,EAAE,CAC7E,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,WAAW,CAAC;AACjC,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,YAAY,EAAE,CAAC;AAEnF,oDAAoD;AACpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;KACrD,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAG/B,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;KAC9E,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC","sourcesContent":["/**\n * founder-schema: the access API\n *\n *   GET  /api/v1/me/access        who I am acting as, what I hold, my rules\n *   PUT  /api/v1/me/active-role   switch role (a staff role needs the MPIN)\n *   POST /api/v1/me/mpin          set the MPIN, once\n *   PUT  /api/v1/me/mpin          change it, with the current one\n *\n * THE MPIN is a 6-digit code that stands between a signed-in member and their\n * staff roles. Signing in proves who you are; the MPIN proves it is still you\n * at the moment you pick up admin powers, on a phone that may have been left\n * unlocked. Set once by its owner; a forgotten one is cleared by a superadmin\n * (an audited action), after which the owner sets a new one. `MPIN_MAX_ATTEMPTS`\n * wrong tries lock it for `MPIN_LOCK_MS`.\n *\n * THE ACTIVE ROLE is per account (the user's ruling, 2026-10-05): switching on\n * one device switches every device. It lasts `ACTIVE_ROLE_TTL_MS`, and the\n * server re-checks it on EVERY request: a role that was revoked, or that\n * expired, is acting as a member again at once, not at the next sign-in.\n *\n * @module founder-schema/access/access\n */\n\nimport { z } from 'zod';\nimport { VALIDATION_MESSAGE } from '../core/validation.js';\nimport { packedRulesSchema } from './permissions.js';\nimport { MEMBER_ROLE, roleSchema } from './roles.js';\n\nexport const MPIN_LENGTH = 6;\n/** Wrong tries before the MPIN locks. */\nexport const MPIN_MAX_ATTEMPTS = 5;\n/** How long a locked MPIN stays locked. */\nexport const MPIN_LOCK_MS = 15 * 60 * 1000;\n\nexport const mpinSchema = z.string().regex(/^\\d{6}$/, VALIDATION_MESSAGE.mpinInvalid);\n\n/** The answer to `GET /me/access`, and to every switch. */\nexport const meAccessResponseSchema = z.object({\n  /** Every role held, member always among them, highest first. */\n  roles: z.array(roleSchema).min(1),\n  /** The role being acted as now. Member when no staff role is switched on. */\n  activeRole: roleSchema,\n  /** When the active staff role lapses back to member. Null while acting as a member. */\n  activeRoleExpiresAt: z.iso.datetime().nullable(),\n  /** Whether an MPIN is set, so the switcher knows to ask for one or to offer setting one. */\n  mpinSet: z.boolean(),\n  /** The active role's permissions, packed (`packRules`). */\n  rules: packedRulesSchema,\n});\nexport type MeAccessResponse = z.infer<typeof meAccessResponseSchema>;\n\n/** `PUT /me/active-role`. Back to member needs nothing; any staff role needs the MPIN. */\nexport const switchRoleBodySchema = z\n  .object({\n    role: roleSchema,\n    mpin: mpinSchema.optional(),\n  })\n  .refine((body) => body.role === MEMBER_ROLE || body.mpin !== undefined, {\n    path: ['mpin'],\n    error: VALIDATION_MESSAGE.mpinRequired,\n  });\nexport type SwitchRoleBody = z.infer<typeof switchRoleBodySchema>;\n\nconst confirmed = <T extends { mpin: string; confirmMpin: string }>(body: T) =>\n  body.mpin === body.confirmMpin;\nconst mismatch = { path: ['confirmMpin'], error: VALIDATION_MESSAGE.mpinMismatch };\n\n/** `POST /me/mpin`: the first MPIN, typed twice. */\nexport const setMpinBodySchema = z\n  .object({ mpin: mpinSchema, confirmMpin: mpinSchema })\n  .refine(confirmed, mismatch);\nexport type SetMpinBody = z.infer<typeof setMpinBodySchema>;\n\n/** `PUT /me/mpin`: the current MPIN, then the new one typed twice. */\nexport const changeMpinBodySchema = z\n  .object({ currentMpin: mpinSchema, mpin: mpinSchema, confirmMpin: mpinSchema })\n  .refine(confirmed, mismatch);\nexport type ChangeMpinBody = z.infer<typeof changeMpinBodySchema>;\n"]}

package/dist/access/permissions.d.ts

@@ -0,0 +1,153 @@
+/**
+ * founder-schema: what a role may do, in CASL's terms
+ *
+ * Permissions are ACTION on SUBJECT, optionally narrowed by conditions on the
+ * subject's fields ("update a Post whose authorId is mine"). The backend writes
+ * one small policy per role from these words; the web receives the resulting
+ * rules and asks the same questions to decide what to draw. Because both sides
+ * spell actions and subjects from this file, a permission check with a typo is
+ * a compile error, not a button that silently never shows.
+ *
+ * The SERVER decides; the web only mirrors. Every rule the web holds came from
+ * the server for the role being acted as, and every request is checked again
+ * on the server, so a tampered client can show itself a button and nothing
+ * more.
+ *
+ * @module founder-schema/access/permissions
+ */
+import type { ForcedSubject, MongoAbility } from '@casl/ability';
+import { z } from 'zod';
+import type { PlatformRole } from './roles.js';
+/**
+ * The verbs.
+ *
+ *   manage    every action (CASL's wildcard). Only superadmin holds it on `all`.
+ *   create, read, update, delete
+ *   moderate  hide, restore or remove someone else's content, act on a report
+ *   assign    grant or revoke (a platform role); take or hand over (a ticket)
+ *   suspend   stop a member signing in to the product, and lift it
+ *   resolve   close a support ticket or a report
+ *   reset     clear a credential its owner forgot (a staff member's MPIN)
+ */
+export declare const ACTION_VALUES: readonly ["manage", "create", "read", "update", "delete", "moderate", "assign", "suspend", "resolve", "reset"];
+export declare const actionSchema: z.ZodEnum<{
+    manage: "manage";
+    create: "create";
+    read: "read";
+    update: "update";
+    delete: "delete";
+    moderate: "moderate";
+    assign: "assign";
+    suspend: "suspend";
+    resolve: "resolve";
+    reset: "reset";
+}>;
+export type Action = z.infer<typeof actionSchema>;
+/**
+ * The things.
+ *
+ *   all               CASL's wildcard subject
+ *   Dashboard         the staff overview: counts and trends
+ *   Member            a person's account in this product
+ *   FounderProfile    a member's public profile
+ *   Post, Poll, Comment
+ *   Report            a member's report of a post, poll or comment
+ *   SupportTicket     a member's request for help
+ *   SavedReply        a support agent's reusable answer
+ *   PlatformRole      a staff role, as something granted and revoked
+ *   AuditEntry        the record of a staff action
+ *   PlatformSettings  product-wide configuration
+ */
+export declare const SUBJECT_VALUES: readonly ["all", "Dashboard", "Member", "FounderProfile", "Post", "Poll", "Comment", "Report", "SupportTicket", "SavedReply", "PlatformRole", "AuditEntry", "PlatformSettings"];
+export declare const subjectSchema: z.ZodEnum<{
+    all: "all";
+    Dashboard: "Dashboard";
+    Member: "Member";
+    FounderProfile: "FounderProfile";
+    Post: "Post";
+    Poll: "Poll";
+    Comment: "Comment";
+    Report: "Report";
+    SupportTicket: "SupportTicket";
+    SavedReply: "SavedReply";
+    PlatformRole: "PlatformRole";
+    AuditEntry: "AuditEntry";
+    PlatformSettings: "PlatformSettings";
+}>;
+export type Subject = z.infer<typeof subjectSchema>;
+/**
+ * The fields a rule may set CONDITIONS on, per subject: the server's stored
+ * names, ids as strings. Declared here so a condition on a field the subject
+ * does not have (`{ ownerId: me }` on a Post) is a compile error, on both sides.
+ *
+ * A web screen does not evaluate these against an API response: a response
+ * names things differently (`author.userId`, not `authorId`). Row-level answers
+ * come from the server on the item itself (`viewer.canEdit`); the web's own
+ * checks are type-level ("may I moderate Reports at all").
+ */
+export interface SubjectFields {
+    Dashboard: Record<never, never>;
+    /** `appRoles` is the staff roles held, so a rule can protect a role ("never suspend a superadmin"). */
+    Member: {
+        _id: string;
+        appRoles: PlatformRole[];
+    };
+    FounderProfile: {
+        userId: string;
+    };
+    Post: {
+        authorId: string;
+    };
+    Poll: {
+        authorId: string;
+    };
+    Comment: {
+        authorId: string;
+    };
+    Report: {
+        reporterId: string;
+        status: string;
+    };
+    SupportTicket: {
+        memberId: string;
+        assigneeId: string | null;
+    };
+    SavedReply: {
+        authorId: string;
+    };
+    /** One role on one person: `memberId` is whose, so "never your own" is a rule too. */
+    PlatformRole: {
+        role: PlatformRole;
+        memberId: string;
+    };
+    /** `actorId` is null for an entry a server script wrote. */
+    AuditEntry: {
+        actorId: string | null;
+    };
+    PlatformSettings: Record<never, never>;
+}
+/** A document tagged with its subject type, as CASL's `subject('Post', doc)` makes one. */
+export type SubjectInstance = {
+    [K in keyof SubjectFields]: SubjectFields[K] & ForcedSubject<K>;
+}[keyof SubjectFields];
+/**
+ * The ability both sides build: the backend from its policy, the web from the
+ * rules the backend sends. Mongo-style conditions, typed by `SubjectFields`.
+ */
+export type AppAbility = MongoAbility<[Action, Subject | SubjectInstance]>;
+/**
+ * Compile-time proof that `SubjectFields` names exactly the subjects, no more
+ * and no fewer: adding a subject without its fields fails the build here.
+ */
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type Assert<T extends true> = T;
+export type EverySubjectHasFields = Assert<Same<keyof SubjectFields, Exclude<Subject, 'all'>>>;
+/**
+ * Rules as they cross the wire: CASL's `packRules` output, an array of
+ * compact arrays. The web unpacks them with `unpackRules` before building its
+ * ability; their inner shape is CASL's, so it is not re-described here.
+ */
+export declare const packedRulesSchema: z.ZodArray<z.ZodArray<z.ZodUnknown>>;
+export type PackedRules = z.infer<typeof packedRulesSchema>;
+export {};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/access/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/access/permissions.ts"],"names":[],"mappings":"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"}

package/dist/access/permissions.js

@@ -0,0 +1,80 @@
+/**
+ * founder-schema: what a role may do, in CASL's terms
+ *
+ * Permissions are ACTION on SUBJECT, optionally narrowed by conditions on the
+ * subject's fields ("update a Post whose authorId is mine"). The backend writes
+ * one small policy per role from these words; the web receives the resulting
+ * rules and asks the same questions to decide what to draw. Because both sides
+ * spell actions and subjects from this file, a permission check with a typo is
+ * a compile error, not a button that silently never shows.
+ *
+ * The SERVER decides; the web only mirrors. Every rule the web holds came from
+ * the server for the role being acted as, and every request is checked again
+ * on the server, so a tampered client can show itself a button and nothing
+ * more.
+ *
+ * @module founder-schema/access/permissions
+ */
+import { z } from 'zod';
+/**
+ * The verbs.
+ *
+ *   manage    every action (CASL's wildcard). Only superadmin holds it on `all`.
+ *   create, read, update, delete
+ *   moderate  hide, restore or remove someone else's content, act on a report
+ *   assign    grant or revoke (a platform role); take or hand over (a ticket)
+ *   suspend   stop a member signing in to the product, and lift it
+ *   resolve   close a support ticket or a report
+ *   reset     clear a credential its owner forgot (a staff member's MPIN)
+ */
+export const ACTION_VALUES = [
+    'manage',
+    'create',
+    'read',
+    'update',
+    'delete',
+    'moderate',
+    'assign',
+    'suspend',
+    'resolve',
+    'reset',
+];
+export const actionSchema = z.enum(ACTION_VALUES);
+/**
+ * The things.
+ *
+ *   all               CASL's wildcard subject
+ *   Dashboard         the staff overview: counts and trends
+ *   Member            a person's account in this product
+ *   FounderProfile    a member's public profile
+ *   Post, Poll, Comment
+ *   Report            a member's report of a post, poll or comment
+ *   SupportTicket     a member's request for help
+ *   SavedReply        a support agent's reusable answer
+ *   PlatformRole      a staff role, as something granted and revoked
+ *   AuditEntry        the record of a staff action
+ *   PlatformSettings  product-wide configuration
+ */
+export const SUBJECT_VALUES = [
+    'all',
+    'Dashboard',
+    'Member',
+    'FounderProfile',
+    'Post',
+    'Poll',
+    'Comment',
+    'Report',
+    'SupportTicket',
+    'SavedReply',
+    'PlatformRole',
+    'AuditEntry',
+    'PlatformSettings',
+];
+export const subjectSchema = z.enum(SUBJECT_VALUES);
+/**
+ * Rules as they cross the wire: CASL's `packRules` output, an array of
+ * compact arrays. The web unpacks them with `unpackRules` before building its
+ * ability; their inner shape is CASL's, so it is not re-described here.
+ */
+export const packedRulesSchema = z.array(z.array(z.unknown()));
+//# sourceMappingURL=permissions.js.map

package/dist/access/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/access/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;CACC,CAAC;AACX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAGlD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK;IACL,WAAW;IACX,QAAQ;IACR,gBAAgB;IAChB,MAAM;IACN,MAAM;IACN,SAAS;IACT,QAAQ;IACR,eAAe;IACf,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,kBAAkB;CACV,CAAC;AACX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAkDpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC","sourcesContent":["/**\n * founder-schema: what a role may do, in CASL's terms\n *\n * Permissions are ACTION on SUBJECT, optionally narrowed by conditions on the\n * subject's fields (\"update a Post whose authorId is mine\"). The backend writes\n * one small policy per role from these words; the web receives the resulting\n * rules and asks the same questions to decide what to draw. Because both sides\n * spell actions and subjects from this file, a permission check with a typo is\n * a compile error, not a button that silently never shows.\n *\n * The SERVER decides; the web only mirrors. Every rule the web holds came from\n * the server for the role being acted as, and every request is checked again\n * on the server, so a tampered client can show itself a button and nothing\n * more.\n *\n * @module founder-schema/access/permissions\n */\n\nimport type { ForcedSubject, MongoAbility } from '@casl/ability';\nimport { z } from 'zod';\nimport type { PlatformRole } from './roles.js';\n\n/**\n * The verbs.\n *\n *   manage    every action (CASL's wildcard). Only superadmin holds it on `all`.\n *   create, read, update, delete\n *   moderate  hide, restore or remove someone else's content, act on a report\n *   assign    grant or revoke (a platform role); take or hand over (a ticket)\n *   suspend   stop a member signing in to the product, and lift it\n *   resolve   close a support ticket or a report\n *   reset     clear a credential its owner forgot (a staff member's MPIN)\n */\nexport const ACTION_VALUES = [\n  'manage',\n  'create',\n  'read',\n  'update',\n  'delete',\n  'moderate',\n  'assign',\n  'suspend',\n  'resolve',\n  'reset',\n] as const;\nexport const actionSchema = z.enum(ACTION_VALUES);\nexport type Action = z.infer<typeof actionSchema>;\n\n/**\n * The things.\n *\n *   all               CASL's wildcard subject\n *   Dashboard         the staff overview: counts and trends\n *   Member            a person's account in this product\n *   FounderProfile    a member's public profile\n *   Post, Poll, Comment\n *   Report            a member's report of a post, poll or comment\n *   SupportTicket     a member's request for help\n *   SavedReply        a support agent's reusable answer\n *   PlatformRole      a staff role, as something granted and revoked\n *   AuditEntry        the record of a staff action\n *   PlatformSettings  product-wide configuration\n */\nexport const SUBJECT_VALUES = [\n  'all',\n  'Dashboard',\n  'Member',\n  'FounderProfile',\n  'Post',\n  'Poll',\n  'Comment',\n  'Report',\n  'SupportTicket',\n  'SavedReply',\n  'PlatformRole',\n  'AuditEntry',\n  'PlatformSettings',\n] as const;\nexport const subjectSchema = z.enum(SUBJECT_VALUES);\nexport type Subject = z.infer<typeof subjectSchema>;\n\n/**\n * The fields a rule may set CONDITIONS on, per subject: the server's stored\n * names, ids as strings. Declared here so a condition on a field the subject\n * does not have (`{ ownerId: me }` on a Post) is a compile error, on both sides.\n *\n * A web screen does not evaluate these against an API response: a response\n * names things differently (`author.userId`, not `authorId`). Row-level answers\n * come from the server on the item itself (`viewer.canEdit`); the web's own\n * checks are type-level (\"may I moderate Reports at all\").\n */\nexport interface SubjectFields {\n  Dashboard: Record<never, never>;\n  /** `appRoles` is the staff roles held, so a rule can protect a role (\"never suspend a superadmin\"). */\n  Member: { _id: string; appRoles: PlatformRole[] };\n  FounderProfile: { userId: string };\n  Post: { authorId: string };\n  Poll: { authorId: string };\n  Comment: { authorId: string };\n  Report: { reporterId: string; status: string };\n  SupportTicket: { memberId: string; assigneeId: string | null };\n  SavedReply: { authorId: string };\n  /** One role on one person: `memberId` is whose, so \"never your own\" is a rule too. */\n  PlatformRole: { role: PlatformRole; memberId: string };\n  /** `actorId` is null for an entry a server script wrote. */\n  AuditEntry: { actorId: string | null };\n  PlatformSettings: Record<never, never>;\n}\n\n/** A document tagged with its subject type, as CASL's `subject('Post', doc)` makes one. */\nexport type SubjectInstance = {\n  [K in keyof SubjectFields]: SubjectFields[K] & ForcedSubject<K>;\n}[keyof SubjectFields];\n\n/**\n * The ability both sides build: the backend from its policy, the web from the\n * rules the backend sends. Mongo-style conditions, typed by `SubjectFields`.\n */\nexport type AppAbility = MongoAbility<[Action, Subject | SubjectInstance]>;\n\n/**\n * Compile-time proof that `SubjectFields` names exactly the subjects, no more\n * and no fewer: adding a subject without its fields fails the build here.\n */\ntype Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;\ntype Assert<T extends true> = T;\nexport type EverySubjectHasFields = Assert<Same<keyof SubjectFields, Exclude<Subject, 'all'>>>;\n\n/**\n * Rules as they cross the wire: CASL's `packRules` output, an array of\n * compact arrays. The web unpacks them with `unpackRules` before building its\n * ability; their inner shape is CASL's, so it is not re-described here.\n */\nexport const packedRulesSchema = z.array(z.array(z.unknown()));\nexport type PackedRules = z.infer<typeof packedRulesSchema>;\n"]}

package/dist/access/roles.d.ts

@@ -0,0 +1,71 @@
+/**
+ * founder-schema: who someone can be in Founder Circle
+ *
+ * Every person is a MEMBER. Some also hold PLATFORM ROLES, the staff who run
+ * the product. A person acts as ONE role at a time (the "active role"), chosen
+ * with the role switcher; what they may do is that role's permissions plus the
+ * member's own, never the union of everything they hold. A superadmin reading
+ * the feed as a member sees what a member sees.
+ *
+ *   superadmin     owns the platform: governance, the staff team, the audit log
+ *   manager        runs the community day to day: members, content, the team
+ *                  of moderators and support agents
+ *   moderator      keeps the feed safe: reports, hiding and removing content
+ *   support_agent  helps members with their account and their problems
+ *   member         everyone, the founder using the product
+ *
+ * THE ONE LIST. The backend's policy, the web's tabs and switcher, and every
+ * request and response that names a role read these values, so a role cannot
+ * exist on one side and not the other. GymMonk and Jansathi each kept their
+ * role list in three or four places, and the copies drifted.
+ *
+ * @module founder-schema/access/roles
+ */
+import { z } from 'zod';
+/** The staff roles, highest first. */
+export declare const PLATFORM_ROLE_VALUES: readonly ["superadmin", "manager", "moderator", "support_agent"];
+export declare const platformRoleSchema: z.ZodEnum<{
+    superadmin: "superadmin";
+    manager: "manager";
+    moderator: "moderator";
+    support_agent: "support_agent";
+}>;
+export type PlatformRole = z.infer<typeof platformRoleSchema>;
+/** Everyone holds it. It is never stored and never granted. */
+export declare const MEMBER_ROLE: "member";
+/**
+ * Every role, highest first: the switcher's order. Nobody LANDS in a staff
+ * role: everyone acts as a member until they switch with their MPIN (see
+ * `access.ts`), so a borrowed phone never opens on a moderation console.
+ */
+export declare const ROLE_VALUES: readonly ["superadmin", "manager", "moderator", "support_agent", "member"];
+export declare const roleSchema: z.ZodEnum<{
+    superadmin: "superadmin";
+    manager: "manager";
+    moderator: "moderator";
+    support_agent: "support_agent";
+    member: "member";
+}>;
+export type Role = z.infer<typeof roleSchema>;
+export declare function isPlatformRole(value: unknown): value is PlatformRole;
+/**
+ * Who may grant or take away each platform role, keyed by the role in
+ * question, listing the roles ACTED AS that may do it. The user's ruling,
+ * 2026-10-05:
+ *
+ *   - only a superadmin makes (or unmakes) a manager;
+ *   - a superadmin or a manager makes a moderator or a support agent;
+ *   - superadmin is never granted through the product: a server script does
+ *     it, so no compromised account can mint another superadmin;
+ *   - nobody changes their own roles (enforced where the change is made).
+ */
+export declare const ROLE_GRANTED_BY: Readonly<Record<PlatformRole, readonly PlatformRole[]>>;
+/** May someone acting as `actingAs` grant or revoke `role`? */
+export declare function canGrantRole(actingAs: Role, role: PlatformRole): boolean;
+/**
+ * How long a staff role stays switched on. After it, the person is back to
+ * acting as a member until they switch again, with their MPIN. A phone left
+ * unlocked on a desk does not stay a moderation console for days.
+ */
+export declare const ACTIVE_ROLE_TTL_MS: number;
+//# sourceMappingURL=roles.d.ts.map

package/dist/access/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/access/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sCAAsC;AACtC,eAAO,MAAM,oBAAoB,kEAKvB,CAAC;AACX,eAAO,MAAM,kBAAkB;;;;;EAA+B,CAAC;AAC/D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,+DAA+D;AAC/D,eAAO,MAAM,WAAW,EAAG,QAAiB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,WAAW,4EAAkD,CAAC;AAC3E,eAAO,MAAM,UAAU;;;;;;EAAsB,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,YAAY,EAAE,CAAC,CAKnF,CAAC;AAEF,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAExE;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAC"}

package/dist/access/roles.js

@@ -0,0 +1,72 @@
+/**
+ * founder-schema: who someone can be in Founder Circle
+ *
+ * Every person is a MEMBER. Some also hold PLATFORM ROLES, the staff who run
+ * the product. A person acts as ONE role at a time (the "active role"), chosen
+ * with the role switcher; what they may do is that role's permissions plus the
+ * member's own, never the union of everything they hold. A superadmin reading
+ * the feed as a member sees what a member sees.
+ *
+ *   superadmin     owns the platform: governance, the staff team, the audit log
+ *   manager        runs the community day to day: members, content, the team
+ *                  of moderators and support agents
+ *   moderator      keeps the feed safe: reports, hiding and removing content
+ *   support_agent  helps members with their account and their problems
+ *   member         everyone, the founder using the product
+ *
+ * THE ONE LIST. The backend's policy, the web's tabs and switcher, and every
+ * request and response that names a role read these values, so a role cannot
+ * exist on one side and not the other. GymMonk and Jansathi each kept their
+ * role list in three or four places, and the copies drifted.
+ *
+ * @module founder-schema/access/roles
+ */
+import { z } from 'zod';
+/** The staff roles, highest first. */
+export const PLATFORM_ROLE_VALUES = [
+    'superadmin',
+    'manager',
+    'moderator',
+    'support_agent',
+];
+export const platformRoleSchema = z.enum(PLATFORM_ROLE_VALUES);
+/** Everyone holds it. It is never stored and never granted. */
+export const MEMBER_ROLE = 'member';
+/**
+ * Every role, highest first: the switcher's order. Nobody LANDS in a staff
+ * role: everyone acts as a member until they switch with their MPIN (see
+ * `access.ts`), so a borrowed phone never opens on a moderation console.
+ */
+export const ROLE_VALUES = [...PLATFORM_ROLE_VALUES, MEMBER_ROLE];
+export const roleSchema = z.enum(ROLE_VALUES);
+export function isPlatformRole(value) {
+    return platformRoleSchema.safeParse(value).success;
+}
+/**
+ * Who may grant or take away each platform role, keyed by the role in
+ * question, listing the roles ACTED AS that may do it. The user's ruling,
+ * 2026-10-05:
+ *
+ *   - only a superadmin makes (or unmakes) a manager;
+ *   - a superadmin or a manager makes a moderator or a support agent;
+ *   - superadmin is never granted through the product: a server script does
+ *     it, so no compromised account can mint another superadmin;
+ *   - nobody changes their own roles (enforced where the change is made).
+ */
+export const ROLE_GRANTED_BY = {
+    superadmin: [],
+    manager: ['superadmin'],
+    moderator: ['superadmin', 'manager'],
+    support_agent: ['superadmin', 'manager'],
+};
+/** May someone acting as `actingAs` grant or revoke `role`? */
+export function canGrantRole(actingAs, role) {
+    return isPlatformRole(actingAs) && ROLE_GRANTED_BY[role].includes(actingAs);
+}
+/**
+ * How long a staff role stays switched on. After it, the person is back to
+ * acting as a member until they switch again, with their MPIN. A phone left
+ * unlocked on a desk does not stay a moderation console for days.
+ */
+export const ACTIVE_ROLE_TTL_MS = 12 * 60 * 60 * 1000;
+//# sourceMappingURL=roles.js.map

package/dist/access/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/access/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sCAAsC;AACtC,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,YAAY;IACZ,SAAS;IACT,WAAW;IACX,eAAe;CACP,CAAC;AACX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;AAG/D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,QAAiB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAG,oBAAoB,EAAE,WAAW,CAAU,CAAC;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAG9C,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAA4D;IACtF,UAAU,EAAE,EAAE;IACd,OAAO,EAAE,CAAC,YAAY,CAAC;IACvB,SAAS,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC;IACpC,aAAa,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC;CACzC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,QAAc,EAAE,IAAkB;IAC7D,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC","sourcesContent":["/**\n * founder-schema: who someone can be in Founder Circle\n *\n * Every person is a MEMBER. Some also hold PLATFORM ROLES, the staff who run\n * the product. A person acts as ONE role at a time (the \"active role\"), chosen\n * with the role switcher; what they may do is that role's permissions plus the\n * member's own, never the union of everything they hold. A superadmin reading\n * the feed as a member sees what a member sees.\n *\n *   superadmin     owns the platform: governance, the staff team, the audit log\n *   manager        runs the community day to day: members, content, the team\n *                  of moderators and support agents\n *   moderator      keeps the feed safe: reports, hiding and removing content\n *   support_agent  helps members with their account and their problems\n *   member         everyone, the founder using the product\n *\n * THE ONE LIST. The backend's policy, the web's tabs and switcher, and every\n * request and response that names a role read these values, so a role cannot\n * exist on one side and not the other. GymMonk and Jansathi each kept their\n * role list in three or four places, and the copies drifted.\n *\n * @module founder-schema/access/roles\n */\n\nimport { z } from 'zod';\n\n/** The staff roles, highest first. */\nexport const PLATFORM_ROLE_VALUES = [\n  'superadmin',\n  'manager',\n  'moderator',\n  'support_agent',\n] as const;\nexport const platformRoleSchema = z.enum(PLATFORM_ROLE_VALUES);\nexport type PlatformRole = z.infer<typeof platformRoleSchema>;\n\n/** Everyone holds it. It is never stored and never granted. */\nexport const MEMBER_ROLE = 'member' as const;\n\n/**\n * Every role, highest first: the switcher's order. Nobody LANDS in a staff\n * role: everyone acts as a member until they switch with their MPIN (see\n * `access.ts`), so a borrowed phone never opens on a moderation console.\n */\nexport const ROLE_VALUES = [...PLATFORM_ROLE_VALUES, MEMBER_ROLE] as const;\nexport const roleSchema = z.enum(ROLE_VALUES);\nexport type Role = z.infer<typeof roleSchema>;\n\nexport function isPlatformRole(value: unknown): value is PlatformRole {\n  return platformRoleSchema.safeParse(value).success;\n}\n\n/**\n * Who may grant or take away each platform role, keyed by the role in\n * question, listing the roles ACTED AS that may do it. The user's ruling,\n * 2026-10-05:\n *\n *   - only a superadmin makes (or unmakes) a manager;\n *   - a superadmin or a manager makes a moderator or a support agent;\n *   - superadmin is never granted through the product: a server script does\n *     it, so no compromised account can mint another superadmin;\n *   - nobody changes their own roles (enforced where the change is made).\n */\nexport const ROLE_GRANTED_BY: Readonly<Record<PlatformRole, readonly PlatformRole[]>> = {\n  superadmin: [],\n  manager: ['superadmin'],\n  moderator: ['superadmin', 'manager'],\n  support_agent: ['superadmin', 'manager'],\n};\n\n/** May someone acting as `actingAs` grant or revoke `role`? */\nexport function canGrantRole(actingAs: Role, role: PlatformRole): boolean {\n  return isPlatformRole(actingAs) && ROLE_GRANTED_BY[role].includes(actingAs);\n}\n\n/**\n * How long a staff role stays switched on. After it, the person is back to\n * acting as a member until they switch again, with their MPIN. A phone left\n * unlocked on a desk does not stay a moderation console for days.\n */\nexport const ACTIVE_ROLE_TTL_MS = 12 * 60 * 60 * 1000;\n"]}