@happyvertical/smrt-users 0.57.1 → 0.57.3

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-users",
-  "packageVersion": "0.57.1",
+  "packageVersion": "0.57.3",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "cd5cf425052f3c1a47b9732fa8240fd12c2be4291a922e4412714b0513bbca2e",
-    "packageJson": "871a2cad86fa16748e09f43dc8edb5f9c6326c4dbcd3ef669b7d0327aa116441",
+    "manifest": "aecb25488c6141cf87d3e8ba61bb54fa3b94ea97712f7d9f9f77cc7b74bda80c",
+    "packageJson": "e2574af9f3e6c489a9c13789cd1166b98a0f84de857279a27427804d3b14758e",
     "agents": "c4ab6a1aae24c0fb687d4d02ef25dcb5e6942ad7e8318e9d0dd8d03d5750b788",
     "moduleDoc:agents/permissions.md": "02b2f03f0e057721369d9c693a624a6fdb3df4935401531a4373ff18229a64be",
     "moduleDoc:agents/oidc-provisioning.md": "b73f3fdaf61136720132a614c7e14237b7bd35f7bf5d43eabb29f565485803b9",
@@ -74,7 +74,7 @@
     "users"
   ],
   "risks": [
-    "cross-package-refs:1",
+    "cross-package-refs:2",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -3194,6 +3194,687 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "MemberClass",
+      "qualifiedName": "@happyvertical/smrt-users:MemberClass",
+      "displayLabelField": "name",
+      "collection": "memberclasses",
+      "description": "A tenant-configured legal class; it has no authority or entitlement effect.",
+      "tableName": "member_classes",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "key",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "description",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "policyMetadata",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMember",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMember",
+      "collection": "legalmembers",
+      "description": "The legal register entry, deliberately separate from RBAC Membership.",
+      "tableName": "legal_members",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "memberClassId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "MemberClass",
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "displayName",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "userId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "profileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "externalPartyRef",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "joinedOn",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "leftOn",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "memberClassId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "MemberClass",
+          "columnType": "UUID"
+        },
+        {
+          "name": "userId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "profileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMemberStatusHistory",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMemberStatusHistory",
+      "collection": "legalmemberstatushistories",
+      "description": "Append-only effective history; current status never erases it.",
+      "tableName": "legal_member_status_history",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "effectiveOn",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sequence",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorRef",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-users:LegalMemberStatusHistory"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMemberReference",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMemberReference",
+      "collection": "legalmemberreferences",
+      "description": "A link to authoritative share/dues/subscription/agreement/ledger evidence.",
+      "tableName": "legal_member_references",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "authoritative",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "effectiveFrom",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "effectiveTo",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "revokesId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMemberReference",
+          "columnType": "UUID"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        },
+        {
+          "name": "revokesId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMemberReference",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-users:LegalMemberReference"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "MemberOfficerAppointment",
+      "qualifiedName": "@happyvertical/smrt-users:MemberOfficerAppointment",
+      "collection": "memberofficerappointments",
+      "description": "A dated register of board/officer appointments; it does not implement elections.",
+      "tableName": "member_officer_appointments",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        },
+        {
+          "name": "role",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "effectiveFrom",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "effectiveTo",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "authority",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "MemberEligibilitySnapshot",
+      "qualifiedName": "@happyvertical/smrt-users:MemberEligibilitySnapshot",
+      "collection": "membereligibilitysnapshots",
+      "tableName": "member_eligibility_snapshots",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        },
+        {
+          "name": "recordDate",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "eligible",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "evidence",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "memberId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "LegalMember",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-users:MemberEligibilitySnapshot"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "MemberClassCollection",
+      "qualifiedName": "@happyvertical/smrt-users:MemberClassCollection",
+      "collection": "memberclasses",
+      "tableName": "member_classes",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMemberCollection",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMemberCollection",
+      "collection": "legalmembers",
+      "tableName": "legal_members",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMemberStatusHistoryCollection",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMemberStatusHistoryCollection",
+      "collection": "legalmemberstatushistories",
+      "tableName": "legal_member_status_history",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LegalMemberReferenceCollection",
+      "qualifiedName": "@happyvertical/smrt-users:LegalMemberReferenceCollection",
+      "collection": "legalmemberreferences",
+      "tableName": "legal_member_references",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "MemberOfficerAppointmentCollection",
+      "qualifiedName": "@happyvertical/smrt-users:MemberOfficerAppointmentCollection",
+      "collection": "memberofficerappointments",
+      "tableName": "member_officer_appointments",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "MemberEligibilitySnapshotCollection",
+      "qualifiedName": "@happyvertical/smrt-users:MemberEligibilitySnapshotCollection",
+      "collection": "membereligibilitysnapshots",
+      "tableName": "member_eligibility_snapshots",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "AccessRequest",
       "qualifiedName": "@happyvertical/smrt-users:AccessRequest",
@@ -7077,12 +7758,12 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 27,
-    "crossPackageRefFields": 1,
+    "foreignKeyFields": 34,
+    "crossPackageRefFields": 2,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 116
+    "uuidColumns": 156
   },
   "agentDoc": "# @happyvertical/smrt-users\n\nMulti-tenant identity, RBAC, hierarchical tenants, sessions, and SvelteKit auth.\n\n## Modules\n\nRead only the module relevant to the change; protocol and provisioning details\nare not prerequisites for unrelated user-package work.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `src/services/PermissionResolver.ts` | permission precedence, inherited memberships, guards, RLS, role seeding | [agents/permissions.md](agents/permissions.md) |\n| `src/services/OidcLoginService.ts`, collections and OIDC handlers | identity reconciliation, transaction boundaries, migration readiness | [agents/oidc-provisioning.md](agents/oidc-provisioning.md) |\n| `src/services/MobileAuthService.ts` | mobile handshake, bearer sessions, bootstrap extension boundary | [agents/mobile-auth.md](agents/mobile-auth.md) |\n| `src/services/TerminalAuthService.ts`, `src/services/LoginAttemptLimiter.ts`, `src/collections/LoginAttemptCollection.ts` | terminal approval concurrency, shared login budget and lockout (#3273), retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |\n| `src/services/DeviceCredentialService.ts` | per-person PIN layered on a device session (#3276), verifier seam for other credential kinds | this file, \"Security boundaries\" |\n| `src/services/PasswordCredentialService.ts`, `src/sveltekit/password-handlers.ts` | email + password sign-in and password lifecycle (#3274); shared scrypt in `credential-hash.ts` | this file, \"Security boundaries\"; README \"Password sign-in\" |\n| `src/retention.ts` | expired session/token/CLI-auth reaping and retention sweep wiring | [agents/retention.md](agents/retention.md) |\n\n## Models and authority\n\n- Users are global; tenant access comes through Membership (unique user/tenant).\n  User email is normalized and globally unique through readonly nullable\n  `emailKey`. `profileId` is a unique cross-package reference: at most one User\n  owns each non-null Profile.\n- Tenant uses STI and a materialized hierarchy, maximum depth 10.\n  `hierarchyPath`/`hierarchyLevel` are derived from `parentTenantId` by\n  `Tenant.save()` on every save (any caller-supplied value is recomputed) and\n  descendants are re-materialized when they change; never hand-maintain them.\n  Legacy rows are backfilled with `smrt db:materialize-tenant-hierarchy`\n  (`materializeTenantHierarchy()`). Tests that need a corrupt path must write it\n  with raw SQL (#3036).\n- Role with `tenantId = null` is available to all tenants; `isSystem` prevents\n  deletion. `inheritsToDescendants` is opt-in. Seed owner/admin/member/viewer\n  through `RoleCollection.seedSystemRoles()` at application initialization.\n- Group roles apply only in their own tenant. Use `getGroupIdsForTenant()`,\n  never cross-tenant `getGroupIds()`, for authorization.\n- Upward visibility is opt-in and read-only: `permissions.ancestorRead`\n  ({ roles, collections, maxDepth? }) lets a DESCENDANT membership contribute\n  declared `<collection>.read` at an ancestor, only when no membership resolved\n  there, intersected with BOTH the role's own catalog grants and the\n  principal's effective permissions in that descendant, and only for SYSTEM\n  roles (a tenant-scoped role sharing a declared slug is ignored). Off by default, never\n  write, never lateral, and never row visibility — sibling rows stay scoped by\n  tenancy/RLS. Read the permissions module before changing it.\n- Membership DENY always wins. Direct inactive membership blocks inherited\n  authority; a direct active membership pins resolution instead of unioning it\n  with ancestors. Read the permissions module before changing these rules.\n- AccessRequest has no generated API/MCP/CLI operations; access it through\n  `AccessRequestService`. Its JSON field is `requestContext`, not reserved\n  slug-scoping `context`.\n\n## Security boundaries\n\n- Generated REST/MCP operations on identity/RBAC models are list/get only.\n  Route authentication does not authorize authority mutations, and these models\n  are not tenant-scoped. Use permission-gated services or explicitly checked\n  consumer handlers. Generated CLI is list/get or closed (`cli: false` for\n  credential/grant models) because agents shell out to it; a `cli` without\n  `include` is full CRUD (#3742). Their catalog slugs stay full via\n  `USERS_AUTHORITY_CATALOG_MODELS`. Preserve the registry assertions in\n  `security-audit-1400.test.ts` and `issue-3742-cli-surface-lockdown.test.ts`.\n- Resource guards take the resource tenant, not the session tenant. Omit a\n  session membership when targeting a different tenant; mismatches fail closed.\n  `loadSessionContext().tenantAuthorization` must be checked by required-tenant\n  consumers: null membership can represent inherited authority.\n- Sessions use secure UUIDs; TTL is seconds (default seven days). Access marks\n  expired sessions EXPIRED. Magic-link tokens are single use.\n- `Session.authMethod` is server-set at mint time and never read from the\n  client; every mint site in this package sets it. A session with\n  `parentSessionId` is valid only while its parent validates\n  (`loadSessionContext` enforces this; there is no FK cascade by design), may\n  not switch to a tenant other than the parent's, and is revoked with its\n  parent by `destroySession`.\n- Credential sign-ins reserve through `LoginAttemptLimiter` BEFORE credential\n  work and key the subject on the submitted identifier, never a resolved user,\n  so unknown and wrong take the same path. Reservations are fail-closed: keep\n  them on failure, release on success or abort, never skip the reserve.\n  Limiter writes are raw SQL and bypass the change feed; the audit sink is the\n  observability seam, and it must never throw into the sign-in path.\n  Subject and source budgets are sized independently (#3531); `source: false`\n  ignores the source key, so a reservation then needs a subject (fail closed).\n  The `source-locked` audit entry never carries a subject or caller metadata.\n- `DeviceCredentialService` accepts a person credential only from a\n  first-class session whose `authMethod` is a device-enrollment method\n  (`terminal` by default) and that the host's `assertEnrolledDevice` confirms.\n  A layered or PIN session can never administer PINs regardless of\n  permissions. PIN hashes carry a per-row salt and the configured pepper;\n  treat an unset pepper as a production misconfiguration.\n- A person session carries the PERSON's authority (resolved from their own\n  membership on every load), never the device account's. `Session.data` keys\n  in `SESSION_DATA_KEYS` are server-set controls enforced by the model:\n  `permissionCeiling` only ever intersects (malformed fails closed to none)\n  and suppresses `superAdminBypass`/`systemContext`; `absoluteExpiresAt`\n  bounds `extend()` and `isValid()`; `idleSeconds` overrides the resolving\n  service's TTL policy. Never write them from client input. The ceiling is a\n  sign-in snapshot; `singleOccupant` revokes other children only AFTER a\n  successful mint. A `mustReset` sign-in mints with an empty ceiling and\n  `setPin` ends that session; do not grant it authority another way.\n- `UsersPasswordCredential` is one row per person, sensitive, with no\n  generated surface; `PasswordCredentialService` and its handlers are its only\n  read/write paths. Sign-in normalizes the email like `emailKey`, reserves\n  before work, always runs one scrypt verify (dummy hash when absent), never\n  creates a user, and maps every non-rate-limit refusal to one\n  `PasswordCredentialError`. It re-checks the credential after the mint (a\n  rehash that keeps row and version is confirmed by re-verifying); the\n  parameter-upgrade write is a guarded UPDATE that must never replace a\n  rotated password, and verification against a weaker stored hash is padded\n  to the policy's scrypt cost. Self-service writes are guarded on the proven\n  credential (first set insert-only); session sweeps run before and after\n  each write. Self-service needs the current password except for a first\n  set; `users.password.manage` follows the PIN's single-tenant target\n  rule and never resets the actor's own. Layered sessions never manage\n  passwords; a `mustChange` sign-in mints an empty ceiling.\n  `replaceForgottenPassword` (#3905, opt-in `recovery`) is the only\n  self-service write without the current password: it decides on the stored\n  session row (owner, first-class, no ceiling, listed non-password/pin\n  `authMethod`, fresh `outOfBandProofAt` stamp) and ends every session,\n  its own included. Never set that stamp from client input.\n- A layered session whose tenant differs from its parent's never loads (null\n  is allowed: narrower). Limiter rows carry `retain_until`; retention must\n  not fall back to a process-wide horizon.\n- `Session.parentSessionId` is the parent's bearer: sensitive, never a\n  `list()` filter (raw-SQL id reads, which also keep revocation sweeps free of\n  caller list bounds), never serialized to clients. `users.pin.manage` reaches\n  only people whose every active membership is in the actor's tenant (the PIN\n  is global per person). A sign-in re-checks the verified\n  credential generation AFTER the mint (`stillValid`); keep that ordering.\n  Operation guards deny outside a session's ceiling; `loadPersonSession`\n  re-checks device enrollment.\n- Tenant switching verifies active membership before writing and rotates the\n  session ID for non-null targets, revoking the old session. Persist the returned\n  `SwitchTenantResult.sessionId`; `switchSessionTenant()` updates the cookie and\n  preserves its security settings. Failed switches mutate nothing; null clears\n  do not rotate, and layered sessions never rotate (a replacement would escape\n  the revocation sweeps they depend on). Layers do not nest. `SessionCollection.setSessionTenant()` is unguarded and must\n  never receive an untrusted tenant ID.\n- OIDC provisioning is atomic and fail-closed. Preserve exact issuer/subject\n  identifiers, claim-source email verification, unique global Person ownership,\n  and transaction-bound reconciliation. Read the OIDC module and canonical\n  scenario matrix before changing any provisioning path.\n\n## Entry points and validation\n\n`src/sveltekit/` owns `createSessionHandler`, `createSessionCookie`,\n`destroySessionCookie`, and `switchSessionTenant`. Use README integration examples\nrather than copying application setup into these instructions.\n\nFrom the repository root:\n\n```bash\npnpm --filter @happyvertical/smrt-users test\npnpm --filter @happyvertical/smrt-users typecheck\npnpm --filter @happyvertical/smrt-users test:postgres\n```\n\nStart with the relevant test file via `test -- src/__tests__/<file>.test.ts`.\nRun `test:postgres` for RLS, principal context, OIDC, or terminal-auth database\nchanges. `typecheck` includes Svelte accessibility checks; plain `tsc` is\ninsufficient. Follow root knowledge freshness checks before shipping.\n",
   "moduleDocs": [