@stll/auth-model 0.0.1-placeholder.0 → 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# `@stll/auth-model`
+
+Portable Better Auth contracts for applications that need identical identity,
+session, account, verification, organization, membership, invitation, and role
+semantics. The package has no database or framework runtime dependency.
+
+The parity manifest pins:
+
+- the Better Auth version and singular core model names;
+- PostgreSQL, snake-case mappings, singular model names, transactional adapters,
+  application-generated string IDs, database-backed session/verification, and
+  timezone-aware timestamps;
+- separate logical and physical field semantics: required/not-null, defaults,
+  update behavior, input/output ownership, sorting, indexes, uniqueness,
+  references, physical names/types, primary keys, and exact index predicates;
+- the organization plugin options and core role grants.
+
+Hosts own runtime tables, adapters, secrets, email delivery, lifecycle hooks, and
+product permissions. Every additional field, index, or plugin model must be
+declared explicitly when comparing the normalized host schema.
+
+```ts
+import {
+  BETTER_AUTH_ADAPTER_OPTIONS,
+  BETTER_AUTH_ORGANIZATION_OPTIONS,
+  BETTER_AUTH_ORGANIZATION_ROLE_GRANTS,
+  BETTER_AUTH_ORGANIZATION_STATEMENTS,
+} from "@stll/auth-model";
+import { createAccessControl } from "better-auth/plugins/access";
+
+const statements = {
+  ...BETTER_AUTH_ORGANIZATION_STATEMENTS,
+  document: ["read", "create", "update", "delete"],
+} as const;
+const ac = createAccessControl(statements);
+
+const owner = ac.newRole({
+  ...BETTER_AUTH_ORGANIZATION_ROLE_GRANTS.owner,
+  document: ["read", "create", "update", "delete"],
+});
+
+const adapterOptions = {
+  provider: "pg",
+  schema,
+  ...BETTER_AUTH_ADAPTER_OPTIONS,
+};
+const organizationOptions = {
+  ...BETTER_AUTH_ORGANIZATION_OPTIONS,
+  ac,
+  roles: { owner },
+};
+```
+
+`compareBetterAuthSchema` accepts a normalized schema and an exact extension
+allowlist. It reports `incompatible` for missing core models or fields, semantic
+drift, undeclared additions, and stale extension declarations. Record and index
+declaration order do not affect the result; index column order remains semantic.
+
+The package intentionally does not export runtime tables, secrets, email
+implementations, lifecycle hooks, or product-specific resources.

package/dist/contract.d.ts

@@ -0,0 +1,414 @@
+//#region src/contract.d.ts
+/** Better Auth version whose logical schema this contract describes. */
+declare const BETTER_AUTH_CONTRACT_VERSION = "1.6.26";
+declare const ORGANIZATION_ROLE_NAMES: readonly ["owner", "admin", "member", "intern", "external"];
+type OrganizationRoleName = (typeof ORGANIZATION_ROLE_NAMES)[number];
+/** Better Auth organization resources. Hosts extend this with product grants. */
+declare const BETTER_AUTH_ORGANIZATION_STATEMENTS: {
+  readonly organization: readonly ["update", "delete"];
+  readonly member: readonly ["create", "update", "delete"];
+  readonly invitation: readonly ["create", "cancel"];
+  readonly team: readonly ["create", "update", "delete"];
+  readonly ac: readonly ["create", "read", "update", "delete"];
+};
+type OrganizationPermissionMap = { [Resource in keyof typeof BETTER_AUTH_ORGANIZATION_STATEMENTS]: (typeof BETTER_AUTH_ORGANIZATION_STATEMENTS)[Resource][number][]; };
+type BetterAuthOrganizationRoleGrants = Record<OrganizationRoleName, OrganizationPermissionMap>;
+/** Core grants shared by every application; product grants remain host-owned. */
+declare const BETTER_AUTH_ORGANIZATION_ROLE_GRANTS: {
+  owner: {
+    organization: ("update" | "delete")[];
+    member: ("update" | "delete" | "create")[];
+    invitation: ("create" | "cancel")[];
+    team: ("update" | "delete" | "create")[];
+    ac: ("update" | "delete" | "create" | "read")[];
+  };
+  admin: {
+    organization: "update"[];
+    member: ("update" | "delete" | "create")[];
+    invitation: ("create" | "cancel")[];
+    team: ("update" | "delete" | "create")[];
+    ac: ("update" | "delete" | "create" | "read")[];
+  };
+  member: {
+    organization: never[];
+    member: never[];
+    invitation: never[];
+    team: never[];
+    ac: "read"[];
+  };
+  intern: {
+    organization: never[];
+    member: never[];
+    invitation: never[];
+    team: never[];
+    ac: never[];
+  };
+  external: {
+    organization: never[];
+    member: never[];
+    invitation: never[];
+    team: never[];
+    ac: never[];
+  };
+};
+/**
+ * Values that change Better Auth's organization authorization semantics.
+ * Hooks, adapters, email delivery, and product-specific options stay local.
+ */
+declare const BETTER_AUTH_ORGANIZATION_OPTIONS: {
+  readonly allowUserToCreateOrganization: true;
+  readonly cancelPendingInvitationsOnReInvite: false;
+  readonly creatorRole: "owner";
+  readonly invitationExpiresIn: number;
+  readonly membershipLimit: 500;
+};
+/** Adapter switches which must match in every host. */
+declare const BETTER_AUTH_ADAPTER_OPTIONS: {
+  readonly camelCase: false;
+  readonly provider: "pg";
+  readonly transaction: true;
+  readonly usePlural: false;
+};
+declare const BETTER_AUTH_CORE_MODEL_NAMES: readonly ["user", "session", "account", "verification", "organization", "member", "invitation"];
+type BetterAuthCoreModelName = (typeof BETTER_AUTH_CORE_MODEL_NAMES)[number];
+type BetterAuthFieldType = "boolean" | "date" | "string";
+type BetterAuthFieldDefault = {
+  kind: "none";
+} | {
+  kind: "runtime";
+} | {
+  kind: "literal";
+  value: boolean | number | string;
+};
+type BetterAuthFieldReference = {
+  field: "id";
+  model: "organization" | "user";
+  onDelete: "cascade" | null;
+};
+type BetterAuthLogicalFieldContract = {
+  default: BetterAuthFieldDefault;
+  indexed: boolean;
+  input: "allowed" | "server-managed";
+  onUpdate: boolean;
+  reference: BetterAuthFieldReference | null;
+  required: boolean;
+  returned: boolean;
+  sortable: boolean;
+  type: BetterAuthFieldType;
+  unique: boolean;
+};
+type BetterAuthDatabaseFieldContract = {
+  columnName: string;
+  columnType: "boolean" | "text" | "timestamptz";
+  default: BetterAuthFieldDefault;
+  notNull: boolean;
+  onUpdate: boolean;
+  precision: number | null;
+  reference: BetterAuthFieldReference | null;
+  storage: "timestamp-with-time-zone" | null;
+  unique: boolean;
+};
+/** Better Auth behavior and physical database guarantees, kept separate. */
+type BetterAuthFieldContract = {
+  database: BetterAuthDatabaseFieldContract;
+  logical: BetterAuthLogicalFieldContract;
+};
+type BetterAuthIndexContract = {
+  fields: readonly string[];
+  predicate: string | null;
+  unique: boolean;
+};
+type BetterAuthModelContract = {
+  fields: Record<string, BetterAuthFieldContract>;
+  indexes: readonly BetterAuthIndexContract[];
+  primaryKey: readonly string[];
+  tableName: string;
+};
+/**
+ * Normalized Better Auth core plus the organization plugin's shared models and
+ * `activeOrganizationId` session extension.
+ */
+declare const BETTER_AUTH_CORE_SCHEMA: {
+  readonly user: {
+    readonly tableName: "user";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [];
+  };
+  readonly session: {
+    readonly tableName: "session";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["userId", "activeOrganizationId"];
+      readonly predicate: null;
+      readonly unique: false;
+    }];
+  };
+  readonly account: {
+    readonly tableName: "account";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["userId"];
+      readonly predicate: null;
+      readonly unique: false;
+    }];
+  };
+  readonly verification: {
+    readonly tableName: "verification";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["identifier"];
+      readonly predicate: null;
+      readonly unique: false;
+    }];
+  };
+  readonly organization: {
+    readonly tableName: "organization";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["slug"];
+      readonly predicate: null;
+      readonly unique: true;
+    }];
+  };
+  readonly member: {
+    readonly tableName: "member";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["organizationId"];
+      readonly predicate: null;
+      readonly unique: false;
+    }, {
+      readonly fields: readonly ["userId"];
+      readonly predicate: null;
+      readonly unique: false;
+    }, {
+      readonly fields: readonly ["organizationId", "userId"];
+      readonly predicate: null;
+      readonly unique: true;
+    }];
+  };
+  readonly invitation: {
+    readonly tableName: "invitation";
+    readonly primaryKey: readonly ["id"];
+    readonly fields: Record<string, BetterAuthFieldContract>;
+    readonly indexes: readonly [{
+      readonly fields: readonly ["organizationId"];
+      readonly predicate: null;
+      readonly unique: false;
+    }, {
+      readonly fields: readonly ["email"];
+      readonly predicate: null;
+      readonly unique: false;
+    }];
+  };
+};
+type BetterAuthAdapterContract = {
+  camelCase: boolean;
+  dateStorage: "timestamp-with-time-zone";
+  idGeneration: "application-string";
+  modelNames: Record<BetterAuthCoreModelName, string>;
+  provider: "pg";
+  sessionStorage: "database";
+  transaction: boolean;
+  usePlural: boolean;
+  verificationStorage: "database";
+};
+declare const BETTER_AUTH_ADAPTER_INVARIANTS: {
+  readonly dateStorage: "timestamp-with-time-zone";
+  readonly idGeneration: "application-string";
+  readonly sessionStorage: "database";
+  readonly verificationStorage: "database";
+  readonly modelNames: {
+    readonly user: "user";
+    readonly session: "session";
+    readonly account: "account";
+    readonly verification: "verification";
+    readonly organization: "organization";
+    readonly member: "member";
+    readonly invitation: "invitation";
+  };
+  readonly camelCase: false;
+  readonly provider: "pg";
+  readonly transaction: true;
+  readonly usePlural: false;
+};
+type BetterAuthSchemaCandidate = {
+  adapter: BetterAuthAdapterContract;
+  models: Record<string, BetterAuthModelContract>;
+};
+type BetterAuthSchemaExtensions = {
+  fields?: Partial<Record<BetterAuthCoreModelName, Record<string, BetterAuthFieldContract>>>;
+  indexes?: Partial<Record<BetterAuthCoreModelName, readonly BetterAuthIndexContract[]>>;
+  models?: readonly string[];
+};
+type BetterAuthSchemaParityIssue = {
+  actual: unknown;
+  expected: unknown;
+  path: string;
+};
+type BetterAuthSchemaParityResult = {
+  status: "compatible";
+} | {
+  issues: BetterAuthSchemaParityIssue[];
+  status: "incompatible";
+};
+/**
+ * Compares a normalized host schema with the complete shared core. Extensions
+ * are exact allowlists: missing, stale, and undeclared additions all fail.
+ */
+declare const compareBetterAuthSchema: (candidate: BetterAuthSchemaCandidate, extensions?: BetterAuthSchemaExtensions) => BetterAuthSchemaParityResult;
+declare const BETTER_AUTH_PARITY_MANIFEST: {
+  readonly adapterInvariants: {
+    readonly dateStorage: "timestamp-with-time-zone";
+    readonly idGeneration: "application-string";
+    readonly sessionStorage: "database";
+    readonly verificationStorage: "database";
+    readonly modelNames: {
+      readonly user: "user";
+      readonly session: "session";
+      readonly account: "account";
+      readonly verification: "verification";
+      readonly organization: "organization";
+      readonly member: "member";
+      readonly invitation: "invitation";
+    };
+    readonly camelCase: false;
+    readonly provider: "pg";
+    readonly transaction: true;
+    readonly usePlural: false;
+  };
+  readonly betterAuthVersion: "1.6.26";
+  readonly options: {
+    readonly allowUserToCreateOrganization: true;
+    readonly cancelPendingInvitationsOnReInvite: false;
+    readonly creatorRole: "owner";
+    readonly invitationExpiresIn: number;
+    readonly membershipLimit: 500;
+  };
+  readonly roleGrants: {
+    owner: {
+      organization: ("update" | "delete")[];
+      member: ("update" | "delete" | "create")[];
+      invitation: ("create" | "cancel")[];
+      team: ("update" | "delete" | "create")[];
+      ac: ("update" | "delete" | "create" | "read")[];
+    };
+    admin: {
+      organization: "update"[];
+      member: ("update" | "delete" | "create")[];
+      invitation: ("create" | "cancel")[];
+      team: ("update" | "delete" | "create")[];
+      ac: ("update" | "delete" | "create" | "read")[];
+    };
+    member: {
+      organization: never[];
+      member: never[];
+      invitation: never[];
+      team: never[];
+      ac: "read"[];
+    };
+    intern: {
+      organization: never[];
+      member: never[];
+      invitation: never[];
+      team: never[];
+      ac: never[];
+    };
+    external: {
+      organization: never[];
+      member: never[];
+      invitation: never[];
+      team: never[];
+      ac: never[];
+    };
+  };
+  readonly roleNames: readonly ["owner", "admin", "member", "intern", "external"];
+  readonly schema: {
+    readonly user: {
+      readonly tableName: "user";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [];
+    };
+    readonly session: {
+      readonly tableName: "session";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["userId", "activeOrganizationId"];
+        readonly predicate: null;
+        readonly unique: false;
+      }];
+    };
+    readonly account: {
+      readonly tableName: "account";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["userId"];
+        readonly predicate: null;
+        readonly unique: false;
+      }];
+    };
+    readonly verification: {
+      readonly tableName: "verification";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["identifier"];
+        readonly predicate: null;
+        readonly unique: false;
+      }];
+    };
+    readonly organization: {
+      readonly tableName: "organization";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["slug"];
+        readonly predicate: null;
+        readonly unique: true;
+      }];
+    };
+    readonly member: {
+      readonly tableName: "member";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["organizationId"];
+        readonly predicate: null;
+        readonly unique: false;
+      }, {
+        readonly fields: readonly ["userId"];
+        readonly predicate: null;
+        readonly unique: false;
+      }, {
+        readonly fields: readonly ["organizationId", "userId"];
+        readonly predicate: null;
+        readonly unique: true;
+      }];
+    };
+    readonly invitation: {
+      readonly tableName: "invitation";
+      readonly primaryKey: readonly ["id"];
+      readonly fields: Record<string, BetterAuthFieldContract>;
+      readonly indexes: readonly [{
+        readonly fields: readonly ["organizationId"];
+        readonly predicate: null;
+        readonly unique: false;
+      }, {
+        readonly fields: readonly ["email"];
+        readonly predicate: null;
+        readonly unique: false;
+      }];
+    };
+  };
+};
+//#endregion
+export { BETTER_AUTH_ADAPTER_INVARIANTS, BETTER_AUTH_ADAPTER_OPTIONS, BETTER_AUTH_CONTRACT_VERSION, BETTER_AUTH_CORE_MODEL_NAMES, BETTER_AUTH_CORE_SCHEMA, BETTER_AUTH_ORGANIZATION_OPTIONS, BETTER_AUTH_ORGANIZATION_ROLE_GRANTS, BETTER_AUTH_ORGANIZATION_STATEMENTS, BETTER_AUTH_PARITY_MANIFEST, BetterAuthAdapterContract, BetterAuthCoreModelName, BetterAuthDatabaseFieldContract, BetterAuthFieldContract, BetterAuthFieldDefault, BetterAuthFieldReference, BetterAuthFieldType, BetterAuthIndexContract, BetterAuthLogicalFieldContract, BetterAuthModelContract, BetterAuthOrganizationRoleGrants, BetterAuthSchemaCandidate, BetterAuthSchemaExtensions, BetterAuthSchemaParityIssue, BetterAuthSchemaParityResult, ORGANIZATION_ROLE_NAMES, OrganizationRoleName, compareBetterAuthSchema };

package/dist/contract.js

@@ -0,0 +1,535 @@
+//#region src/contract.ts
+/** Better Auth version whose logical schema this contract describes. */
+const BETTER_AUTH_CONTRACT_VERSION = "1.6.26";
+const ORGANIZATION_ROLE_NAMES = [
+	"owner",
+	"admin",
+	"member",
+	"intern",
+	"external"
+];
+/** Better Auth organization resources. Hosts extend this with product grants. */
+const BETTER_AUTH_ORGANIZATION_STATEMENTS = {
+	organization: ["update", "delete"],
+	member: [
+		"create",
+		"update",
+		"delete"
+	],
+	invitation: ["create", "cancel"],
+	team: [
+		"create",
+		"update",
+		"delete"
+	],
+	ac: [
+		"create",
+		"read",
+		"update",
+		"delete"
+	]
+};
+/** Core grants shared by every application; product grants remain host-owned. */
+const BETTER_AUTH_ORGANIZATION_ROLE_GRANTS = {
+	owner: {
+		organization: ["update", "delete"],
+		member: [
+			"create",
+			"update",
+			"delete"
+		],
+		invitation: ["create", "cancel"],
+		team: [
+			"create",
+			"update",
+			"delete"
+		],
+		ac: [
+			"create",
+			"read",
+			"update",
+			"delete"
+		]
+	},
+	admin: {
+		organization: ["update"],
+		member: [
+			"create",
+			"update",
+			"delete"
+		],
+		invitation: ["create", "cancel"],
+		team: [
+			"create",
+			"update",
+			"delete"
+		],
+		ac: [
+			"create",
+			"read",
+			"update",
+			"delete"
+		]
+	},
+	member: {
+		organization: [],
+		member: [],
+		invitation: [],
+		team: [],
+		ac: ["read"]
+	},
+	intern: {
+		organization: [],
+		member: [],
+		invitation: [],
+		team: [],
+		ac: []
+	},
+	external: {
+		organization: [],
+		member: [],
+		invitation: [],
+		team: [],
+		ac: []
+	}
+};
+/**
+* Values that change Better Auth's organization authorization semantics.
+* Hooks, adapters, email delivery, and product-specific options stay local.
+*/
+const BETTER_AUTH_ORGANIZATION_OPTIONS = {
+	allowUserToCreateOrganization: true,
+	cancelPendingInvitationsOnReInvite: false,
+	creatorRole: "owner",
+	invitationExpiresIn: 172800,
+	membershipLimit: 500
+};
+/** Adapter switches which must match in every host. */
+const BETTER_AUTH_ADAPTER_OPTIONS = {
+	camelCase: false,
+	provider: "pg",
+	transaction: true,
+	usePlural: false
+};
+const BETTER_AUTH_CORE_MODEL_NAMES = [
+	"user",
+	"session",
+	"account",
+	"verification",
+	"organization",
+	"member",
+	"invitation"
+];
+const noDefault = { kind: "none" };
+const runtimeDefault = { kind: "runtime" };
+const field = (type, options = {}) => ({
+	database: {
+		default: options.database?.default ?? noDefault,
+		notNull: options.database?.notNull ?? options.required ?? false,
+		onUpdate: options.database?.onUpdate ?? false,
+		reference: options.database?.reference ?? (options.reference?.onDelete === "cascade" ? options.reference : null),
+		storage: type === "date" ? "timestamp-with-time-zone" : null,
+		unique: options.database?.unique ?? options.unique ?? false
+	},
+	logical: {
+		default: options.default ?? noDefault,
+		indexed: options.indexed ?? false,
+		input: options.input ?? "allowed",
+		onUpdate: options.onUpdate ?? false,
+		reference: options.reference ?? null,
+		required: options.required ?? false,
+		returned: options.returned ?? true,
+		sortable: options.sortable ?? false,
+		type,
+		unique: options.unique ?? false
+	}
+});
+const toSnakeCase = (value) => value.replaceAll(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`);
+const databaseColumnType = (type) => {
+	if (type === "date") return "timestamptz";
+	if (type === "boolean") return "boolean";
+	return "text";
+};
+const withPhysicalNames = (drafts) => {
+	const result = {};
+	for (const [name, draft] of Object.entries(drafts)) {
+		const type = draft.logical.type;
+		result[name] = {
+			...draft,
+			database: {
+				...draft.database,
+				columnName: toSnakeCase(name),
+				columnType: databaseColumnType(type),
+				precision: null
+			}
+		};
+	}
+	return result;
+};
+const idField = field("string", {
+	default: runtimeDefault,
+	input: "server-managed",
+	required: true
+});
+const runtimeDate = field("date", {
+	default: runtimeDefault,
+	required: true,
+	database: { default: runtimeDefault }
+});
+const runtimeUpdatedDate = field("date", {
+	default: runtimeDefault,
+	onUpdate: true,
+	required: true,
+	database: {
+		default: runtimeDefault,
+		onUpdate: true
+	}
+});
+const updatedDate = field("date", {
+	onUpdate: true,
+	required: true,
+	database: { onUpdate: true }
+});
+const userReference = {
+	field: "id",
+	model: "user",
+	onDelete: "cascade"
+};
+const organizationReference = {
+	field: "id",
+	model: "organization",
+	onDelete: null
+};
+const organizationDatabaseReference = {
+	...organizationReference,
+	onDelete: "cascade"
+};
+const userPluginReference = {
+	...userReference,
+	onDelete: null
+};
+/**
+* Normalized Better Auth core plus the organization plugin's shared models and
+* `activeOrganizationId` session extension.
+*/
+const BETTER_AUTH_CORE_SCHEMA = {
+	user: {
+		tableName: "user",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			name: field("string", {
+				required: true,
+				sortable: true
+			}),
+			email: field("string", {
+				required: true,
+				sortable: true,
+				unique: true
+			}),
+			emailVerified: field("boolean", {
+				default: {
+					kind: "literal",
+					value: false
+				},
+				input: "server-managed",
+				required: true,
+				database: { default: {
+					kind: "literal",
+					value: false
+				} }
+			}),
+			image: field("string"),
+			createdAt: runtimeDate,
+			updatedAt: runtimeUpdatedDate
+		}),
+		indexes: []
+	},
+	session: {
+		tableName: "session",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			expiresAt: field("date", { required: true }),
+			token: field("string", {
+				required: true,
+				unique: true
+			}),
+			createdAt: runtimeDate,
+			updatedAt: updatedDate,
+			ipAddress: field("string"),
+			userAgent: field("string"),
+			userId: field("string", {
+				indexed: true,
+				reference: userReference,
+				required: true
+			}),
+			activeOrganizationId: field("string", { input: "server-managed" })
+		}),
+		indexes: [{
+			fields: ["userId", "activeOrganizationId"],
+			predicate: null,
+			unique: false
+		}]
+	},
+	account: {
+		tableName: "account",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			accountId: field("string", { required: true }),
+			providerId: field("string", { required: true }),
+			userId: field("string", {
+				indexed: true,
+				reference: userReference,
+				required: true
+			}),
+			accessToken: field("string", { returned: false }),
+			refreshToken: field("string", { returned: false }),
+			idToken: field("string", { returned: false }),
+			accessTokenExpiresAt: field("date", { returned: false }),
+			refreshTokenExpiresAt: field("date", { returned: false }),
+			scope: field("string"),
+			password: field("string", { returned: false }),
+			createdAt: runtimeDate,
+			updatedAt: updatedDate
+		}),
+		indexes: [{
+			fields: ["userId"],
+			predicate: null,
+			unique: false
+		}]
+	},
+	verification: {
+		tableName: "verification",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			identifier: field("string", {
+				indexed: true,
+				required: true
+			}),
+			value: field("string", { required: true }),
+			expiresAt: field("date", { required: true }),
+			createdAt: runtimeDate,
+			updatedAt: runtimeUpdatedDate
+		}),
+		indexes: [{
+			fields: ["identifier"],
+			predicate: null,
+			unique: false
+		}]
+	},
+	organization: {
+		tableName: "organization",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			name: field("string", {
+				required: true,
+				sortable: true
+			}),
+			slug: field("string", {
+				indexed: true,
+				required: true,
+				sortable: true,
+				unique: true
+			}),
+			logo: field("string"),
+			createdAt: field("date", { required: true }),
+			metadata: field("string")
+		}),
+		indexes: [{
+			fields: ["slug"],
+			predicate: null,
+			unique: true
+		}]
+	},
+	member: {
+		tableName: "member",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			organizationId: field("string", {
+				database: { reference: organizationDatabaseReference },
+				indexed: true,
+				reference: organizationReference,
+				required: true
+			}),
+			userId: field("string", {
+				database: { reference: userReference },
+				indexed: true,
+				reference: userPluginReference,
+				required: true
+			}),
+			role: field("string", {
+				default: {
+					kind: "literal",
+					value: "member"
+				},
+				required: true,
+				sortable: true,
+				database: { default: {
+					kind: "literal",
+					value: "member"
+				} }
+			}),
+			createdAt: field("date", { required: true })
+		}),
+		indexes: [
+			{
+				fields: ["organizationId"],
+				predicate: null,
+				unique: false
+			},
+			{
+				fields: ["userId"],
+				predicate: null,
+				unique: false
+			},
+			{
+				fields: ["organizationId", "userId"],
+				predicate: null,
+				unique: true
+			}
+		]
+	},
+	invitation: {
+		tableName: "invitation",
+		primaryKey: ["id"],
+		fields: withPhysicalNames({
+			id: idField,
+			organizationId: field("string", {
+				database: { reference: organizationDatabaseReference },
+				indexed: true,
+				reference: organizationReference,
+				required: true
+			}),
+			email: field("string", {
+				indexed: true,
+				required: true,
+				sortable: true
+			}),
+			role: field("string", { sortable: true }),
+			status: field("string", {
+				default: {
+					kind: "literal",
+					value: "pending"
+				},
+				required: true,
+				sortable: true,
+				database: { default: {
+					kind: "literal",
+					value: "pending"
+				} }
+			}),
+			expiresAt: field("date", { required: true }),
+			createdAt: runtimeDate,
+			inviterId: field("string", {
+				database: { reference: userReference },
+				reference: userPluginReference,
+				required: true
+			})
+		}),
+		indexes: [{
+			fields: ["organizationId"],
+			predicate: null,
+			unique: false
+		}, {
+			fields: ["email"],
+			predicate: null,
+			unique: false
+		}]
+	}
+};
+const BETTER_AUTH_ADAPTER_INVARIANTS = {
+	...BETTER_AUTH_ADAPTER_OPTIONS,
+	dateStorage: "timestamp-with-time-zone",
+	idGeneration: "application-string",
+	sessionStorage: "database",
+	verificationStorage: "database",
+	modelNames: {
+		user: "user",
+		session: "session",
+		account: "account",
+		verification: "verification",
+		organization: "organization",
+		member: "member",
+		invitation: "invitation"
+	}
+};
+const compareCodeUnits = (left, right) => {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+};
+const canonicalize = (value) => {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value === null || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).toSorted(([left], [right]) => compareCodeUnits(left, right)).map(([key, child]) => [key, canonicalize(child)]));
+};
+const canonical = (value) => JSON.stringify(canonicalize(value));
+const sortIndexes = (indexes) => indexes.toSorted((left, right) => compareCodeUnits(canonical(left), canonical(right)));
+const compare = (issues, path, actual, expected) => {
+	if (canonical(actual) === canonical(expected)) return;
+	issues.push({
+		actual,
+		expected,
+		path
+	});
+};
+/**
+* Compares a normalized host schema with the complete shared core. Extensions
+* are exact allowlists: missing, stale, and undeclared additions all fail.
+*/
+const compareBetterAuthSchema = (candidate, extensions = {}) => {
+	const issues = [];
+	compare(issues, "adapter", candidate.adapter, BETTER_AUTH_ADAPTER_INVARIANTS);
+	const coreModelNames = new Set(BETTER_AUTH_CORE_MODEL_NAMES);
+	for (const model of extensions.models ?? []) if (coreModelNames.has(model)) issues.push({
+		actual: "core model",
+		expected: "new extension model",
+		path: `extensions.models.${model}`
+	});
+	const expectedModelNames = [...BETTER_AUTH_CORE_MODEL_NAMES, ...extensions.models ?? []].toSorted();
+	compare(issues, "models", Object.keys(candidate.models).toSorted(), expectedModelNames);
+	for (const model of BETTER_AUTH_CORE_MODEL_NAMES) {
+		const actual = candidate.models[model];
+		const core = BETTER_AUTH_CORE_SCHEMA[model];
+		if (!actual) {
+			issues.push({
+				actual: void 0,
+				expected: "core model",
+				path: model
+			});
+			continue;
+		}
+		compare(issues, `${model}.tableName`, actual.tableName, core.tableName);
+		compare(issues, `${model}.primaryKey`, actual.primaryKey, core.primaryKey);
+		const extensionFields = extensions.fields?.[model] ?? {};
+		for (const fieldName of Object.keys(extensionFields)) if (fieldName in core.fields) issues.push({
+			actual: "core field",
+			expected: "new extension field",
+			path: `extensions.${model}.${fieldName}`
+		});
+		compare(issues, `${model}.fields`, actual.fields, {
+			...extensionFields,
+			...core.fields
+		});
+		compare(issues, `${model}.indexes`, sortIndexes(actual.indexes), sortIndexes([...core.indexes, ...extensions.indexes?.[model] ?? []]));
+	}
+	if (issues.length === 0) return { status: "compatible" };
+	return {
+		issues,
+		status: "incompatible"
+	};
+};
+const BETTER_AUTH_PARITY_MANIFEST = {
+	adapterInvariants: BETTER_AUTH_ADAPTER_INVARIANTS,
+	betterAuthVersion: BETTER_AUTH_CONTRACT_VERSION,
+	options: BETTER_AUTH_ORGANIZATION_OPTIONS,
+	roleGrants: BETTER_AUTH_ORGANIZATION_ROLE_GRANTS,
+	roleNames: ORGANIZATION_ROLE_NAMES,
+	schema: BETTER_AUTH_CORE_SCHEMA
+};
+//#endregion
+export { BETTER_AUTH_ADAPTER_INVARIANTS, BETTER_AUTH_ADAPTER_OPTIONS, BETTER_AUTH_CONTRACT_VERSION, BETTER_AUTH_CORE_MODEL_NAMES, BETTER_AUTH_CORE_SCHEMA, BETTER_AUTH_ORGANIZATION_OPTIONS, BETTER_AUTH_ORGANIZATION_ROLE_GRANTS, BETTER_AUTH_ORGANIZATION_STATEMENTS, BETTER_AUTH_PARITY_MANIFEST, ORGANIZATION_ROLE_NAMES, compareBetterAuthSchema };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@stll/auth-model",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. Real releases are published from stella/stella via GitHub Actions.",
-  "license": "Apache-2.0"
+  "version": "0.1.0",
+  "description": "Portable Better Auth core contract and parity checks.",
+  "keywords": [
+    "authentication",
+    "better-auth",
+    "multitenancy",
+    "organizations",
+    "typescript"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/auth-model",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/auth-model"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test src",
+    "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/auth-model",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/auth-model",
+    "format": "oxfmt .",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@stll/typescript-config": "0.0.0",
+    "better-auth": "1.6.26",
+    "bun-types": "1.4.0",
+    "tsdown": "0.22.14"
+  },
+  "main": "./dist/contract.js",
+  "types": "./dist/contract.d.ts"
 }