@happyvertical/smrt-users 0.52.0 → 0.53.5

package/dist/smrt-knowledge.json

@@ -3,18 +3,18 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-users",
-  "packageVersion": "0.52.0",
+  "packageVersion": "0.53.5",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "bf43eb6941f3d30ddd5106bf17478d7b05ecda56fa632bdc32e34c46d5285b1c",
-    "packageJson": "56710fe63eb927dc3f6632196acaaf149389a1efcce248bff1bd2b583ee4973d",
-    "agents": "c1bd1dcae5f1662f31d01d0cff19cb3f774715eb71ecfd249eb429e5f64a3eb7",
-    "moduleDoc:agents/permissions.md": "b5be3f5b84b409cb6e62080e2d7a75b67e0763266c11054045c5c401b84f8dd6",
+    "manifest": "272762d139d7b14daf501ff723c9e5587f0acdb46f60f405f1bf65d7f04dc9c6",
+    "packageJson": "fc0002c8def67fa279b4b897489ea8cb0ff3e2986122d8b67f4995fae1a82a4f",
+    "agents": "a0c6228ba98d46fc4bb2d39d6cc857c0a8a15571661169d2f8ffdbd9c1b0b966",
+    "moduleDoc:agents/permissions.md": "5f6c0afab7e1fd0887b0d29b5a5b5ab2635694207bade70145d3cbfdb62ba78c",
     "moduleDoc:agents/oidc-provisioning.md": "5efa607ff23b9a693391e0c02670324a8cea4114d4968c9718f10a763da919c6",
     "moduleDoc:agents/mobile-auth.md": "25e85e83f43e3a46383a92fa809f3a003b4545c3026e78dbe1bccbbc35161e18",
     "moduleDoc:agents/terminal-auth-testing.md": "8a84c16a19e381427aed81d3b1882344c427fe22a70e87f5ac2db836b1a6822d",
-    "moduleDoc:agents/retention.md": "425c0a34ed33969badfef699751bfa670bdf618eda65e079e00815620aabed68"
+    "moduleDoc:agents/retention.md": "073874bf16ce3fbbc503157679dc7fe69800fb39a59e40299bcc713f099bf3d8"
   },
   "exports": [
     ".",
@@ -968,6 +968,133 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "UsersLoginAttemptCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersLoginAttemptCollection",
+      "collection": "usersloginattempts",
+      "tableName": "users_login_attempts",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "deleteIdle",
+        "recordFailure",
+        "releaseAttempt",
+        "reserveAttempt"
+      ],
+      "methodSignatures": [
+        {
+          "name": "deleteIdle",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<number>"
+        },
+        {
+          "name": "recordFailure",
+          "async": true,
+          "params": [
+            "input: RecordLoginFailureInput"
+          ],
+          "returns": "Promise<RecordedLoginFailure>"
+        },
+        {
+          "name": "releaseAttempt",
+          "async": true,
+          "params": [
+            "limiterKey: string",
+            "windowStartedAt: string",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "reserveAttempt",
+          "async": true,
+          "params": [
+            "input: ReserveLoginAttemptInput"
+          ],
+          "returns": "Promise<LoginAttemptReservation>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteIdle",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAttemptCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "recordFailure",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAttemptCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "releaseAttempt",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAttemptCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "reserveAttempt",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAttemptCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersLoginAuditEventCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersLoginAuditEventCollection",
+      "collection": "usersloginauditevents",
+      "tableName": "users_login_audit_events",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "deleteOlderThan"
+      ],
+      "methodSignatures": [
+        {
+          "name": "deleteOlderThan",
+          "async": true,
+          "params": [
+            "maxAgeMs: number",
+            "options?: object"
+          ],
+          "returns": "Promise<number>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteOlderThan",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAuditEventCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "UsersMagicLinkTokenCollection",
       "qualifiedName": "@happyvertical/smrt-users:UsersMagicLinkTokenCollection",
@@ -1752,6 +1879,77 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "UsersPinCredentialCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersPinCredentialCollection",
+      "collection": "userspincredentials",
+      "tableName": "users_pin_credentials",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "deleteByUserId",
+        "findByUserId",
+        "upsertForUser"
+      ],
+      "methodSignatures": [
+        {
+          "name": "deleteByUserId",
+          "async": true,
+          "params": [
+            "userId: string"
+          ],
+          "returns": "Promise<boolean>"
+        },
+        {
+          "name": "findByUserId",
+          "async": true,
+          "params": [
+            "userId: string"
+          ],
+          "returns": "Promise<UsersPinCredential | null>"
+        },
+        {
+          "name": "upsertForUser",
+          "async": true,
+          "params": [
+            "userId: string",
+            "write: PinCredentialWrite"
+          ],
+          "returns": "Promise<UsersPinCredential>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteByUserId",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersPinCredentialCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "findByUserId",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersPinCredentialCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "upsertForUser",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersPinCredentialCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "ResourceGrantCollection",
       "qualifiedName": "@happyvertical/smrt-users:ResourceGrantCollection",
@@ -2300,10 +2498,13 @@
         "deleteExpired",
         "deleteUserSessions",
         "findByUser",
+        "findChildren",
         "findValidSession",
         "getSessionData",
+        "revokeChildren",
         "revokeSession",
         "revokeUserSessions",
+        "revokeUserSessionsByAuthMethod",
         "setSessionData",
         "setSessionTenant",
         "touch"
@@ -2349,6 +2550,14 @@
           ],
           "returns": "Promise<Session[]>"
         },
+        {
+          "name": "findChildren",
+          "async": true,
+          "params": [
+            "parentSessionId: string"
+          ],
+          "returns": "Promise<Session[]>"
+        },
         {
           "name": "findValidSession",
           "async": true,
@@ -2366,6 +2575,15 @@
           ],
           "returns": "Promise<T | undefined>"
         },
+        {
+          "name": "revokeChildren",
+          "async": true,
+          "params": [
+            "parentSessionId: string",
+            "options?: object"
+          ],
+          "returns": "Promise<number>"
+        },
         {
           "name": "revokeSession",
           "async": true,
@@ -2382,6 +2600,16 @@
           ],
           "returns": "Promise<number>"
         },
+        {
+          "name": "revokeUserSessionsByAuthMethod",
+          "async": true,
+          "params": [
+            "userId: string",
+            "authMethod: SessionAuthMethod",
+            "options?: object"
+          ],
+          "returns": "Promise<number>"
+        },
         {
           "name": "setSessionData",
           "async": true,
@@ -2421,6 +2649,30 @@
           "path": "/sessions/createSession",
           "method": "POST"
         },
+        {
+          "kind": "api",
+          "name": "sessions.findChildren",
+          "operation": "findChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection",
+          "path": "/sessions/findChildren",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "sessions.revokeChildren",
+          "operation": "revokeChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection",
+          "path": "/sessions/revokeChildren",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "sessions.revokeUserSessionsByAuthMethod",
+          "operation": "revokeUserSessionsByAuthMethod",
+          "objectName": "@happyvertical/smrt-users:SessionCollection",
+          "path": "/sessions/revokeUserSessionsByAuthMethod",
+          "method": "POST"
+        },
         {
           "kind": "api",
           "name": "sessions.findValidSession",
@@ -2515,6 +2767,24 @@
           "operation": "createSession",
           "objectName": "@happyvertical/smrt-users:SessionCollection"
         },
+        {
+          "kind": "cli",
+          "name": "sessioncollection_findChildren",
+          "operation": "findChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
+        {
+          "kind": "cli",
+          "name": "sessioncollection_revokeChildren",
+          "operation": "revokeChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
+        {
+          "kind": "cli",
+          "name": "sessioncollection_revokeUserSessionsByAuthMethod",
+          "operation": "revokeUserSessionsByAuthMethod",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
         {
           "kind": "cli",
           "name": "sessioncollection_findValidSession",
@@ -2587,6 +2857,24 @@
           "operation": "createSession",
           "objectName": "@happyvertical/smrt-users:SessionCollection"
         },
+        {
+          "kind": "mcp",
+          "name": "sessioncollection_findchildren",
+          "operation": "findChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
+        {
+          "kind": "mcp",
+          "name": "sessioncollection_revokechildren",
+          "operation": "revokeChildren",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
+        {
+          "kind": "mcp",
+          "name": "sessioncollection_revokeusersessionsbyauthmethod",
+          "operation": "revokeUserSessionsByAuthMethod",
+          "objectName": "@happyvertical/smrt-users:SessionCollection"
+        },
         {
           "kind": "mcp",
           "name": "sessioncollection_findvalidsession",
@@ -4652,6 +4940,166 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "UsersLoginAttempt",
+      "qualifiedName": "@happyvertical/smrt-users:UsersLoginAttempt",
+      "collection": "usersloginattempts",
+      "tableName": "users_login_attempts",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "limiterKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scope",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "attemptCount",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "windowStartedAt",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "failureStreak",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "lockedUntil",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastFailedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "retainUntil",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersLoginAuditEvent",
+      "qualifiedName": "@happyvertical/smrt-users:UsersLoginAuditEvent",
+      "collection": "usersloginauditevents",
+      "tableName": "users_login_audit_events",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "outcome",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "subjectKeyHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceKeyHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "retryAfterSeconds",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "occurredAt",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getMetadata",
+        "setMetadata"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getMetadata",
+          "returns": "Record<string, unknown>"
+        },
+        {
+          "name": "setMetadata",
+          "params": [
+            "value: Record<string, unknown>"
+          ],
+          "returns": "void"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getMetadata",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAuditEvent"
+        },
+        {
+          "kind": "api",
+          "operation": "setMetadata",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-users:UsersLoginAuditEvent"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "UsersMagicLinkToken",
       "qualifiedName": "@happyvertical/smrt-users:UsersMagicLinkToken",
@@ -5271,6 +5719,66 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "UsersPinCredential",
+      "qualifiedName": "@happyvertical/smrt-users:UsersPinCredential",
+      "collection": "userspincredentials",
+      "tableName": "users_pin_credentials",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "userId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "version",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 1
+        },
+        {
+          "name": "mustReset",
+          "type": "boolean",
+          "required": true,
+          "columnType": "BOOLEAN",
+          "default": false
+        },
+        {
+          "name": "rotatedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "rotatedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "userId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "User",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "ResourceGrant",
       "qualifiedName": "@happyvertical/smrt-users:ResourceGrant",
@@ -5665,6 +6173,10 @@
         }
       ],
       "methods": [],
+      "conflictColumns": [
+        "role_id",
+        "permission_id"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -5792,6 +6304,12 @@
           "required": false,
           "columnType": "JSON",
           "default": {}
+        },
+        {
+          "name": "authMethod",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         }
       ],
       "relationships": [
@@ -5812,8 +6330,12 @@
       ],
       "methods": [
         "extend",
+        "getAbsoluteExpiry",
         "getData",
+        "getIdleSeconds",
+        "getPermissionCeiling",
         "isExpired",
+        "isLayered",
         "isRevoked",
         "isValid",
         "recordActivity",
@@ -5831,6 +6353,10 @@
           ],
           "returns": "void"
         },
+        {
+          "name": "getAbsoluteExpiry",
+          "returns": "Date | null"
+        },
         {
           "name": "getData",
           "params": [
@@ -5838,10 +6364,22 @@
           ],
           "returns": "T | undefined"
         },
+        {
+          "name": "getIdleSeconds",
+          "returns": "number | null"
+        },
+        {
+          "name": "getPermissionCeiling",
+          "returns": "string[] | null"
+        },
         {
           "name": "isExpired",
           "returns": "boolean"
         },
+        {
+          "name": "isLayered",
+          "returns": "boolean"
+        },
         {
           "name": "isRevoked",
           "returns": "boolean"
@@ -5942,6 +6480,30 @@
           "operation": "delete",
           "objectName": "@happyvertical/smrt-users:Session"
         },
+        {
+          "kind": "cli",
+          "name": "session_isLayered",
+          "operation": "isLayered",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
+        {
+          "kind": "cli",
+          "name": "session_getAbsoluteExpiry",
+          "operation": "getAbsoluteExpiry",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
+        {
+          "kind": "cli",
+          "name": "session_getIdleSeconds",
+          "operation": "getIdleSeconds",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
+        {
+          "kind": "cli",
+          "name": "session_getPermissionCeiling",
+          "operation": "getPermissionCeiling",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
         {
           "kind": "cli",
           "name": "session_isValid",
@@ -6017,6 +6579,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-users:Session"
         },
+        {
+          "kind": "api",
+          "operation": "getAbsoluteExpiry",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
         {
           "kind": "api",
           "operation": "getData",
@@ -6024,6 +6593,20 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-users:Session"
         },
+        {
+          "kind": "api",
+          "operation": "getIdleSeconds",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
+        {
+          "kind": "api",
+          "operation": "getPermissionCeiling",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
         {
           "kind": "api",
           "operation": "isExpired",
@@ -6031,6 +6614,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-users:Session"
         },
+        {
+          "kind": "api",
+          "operation": "isLayered",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:Session"
+        },
         {
           "kind": "api",
           "operation": "isRevoked",
@@ -8400,6 +8990,30 @@
       "path": "/sessions/createSession",
       "method": "POST"
     },
+    {
+      "kind": "api",
+      "name": "sessions.findChildren",
+      "operation": "findChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection",
+      "path": "/sessions/findChildren",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "sessions.revokeChildren",
+      "operation": "revokeChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection",
+      "path": "/sessions/revokeChildren",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "sessions.revokeUserSessionsByAuthMethod",
+      "operation": "revokeUserSessionsByAuthMethod",
+      "objectName": "@happyvertical/smrt-users:SessionCollection",
+      "path": "/sessions/revokeUserSessionsByAuthMethod",
+      "method": "POST"
+    },
     {
       "kind": "api",
       "name": "sessions.findValidSession",
@@ -8494,6 +9108,24 @@
       "operation": "createSession",
       "objectName": "@happyvertical/smrt-users:SessionCollection"
     },
+    {
+      "kind": "cli",
+      "name": "sessioncollection_findChildren",
+      "operation": "findChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
+    {
+      "kind": "cli",
+      "name": "sessioncollection_revokeChildren",
+      "operation": "revokeChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
+    {
+      "kind": "cli",
+      "name": "sessioncollection_revokeUserSessionsByAuthMethod",
+      "operation": "revokeUserSessionsByAuthMethod",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
     {
       "kind": "cli",
       "name": "sessioncollection_findValidSession",
@@ -8566,6 +9198,24 @@
       "operation": "createSession",
       "objectName": "@happyvertical/smrt-users:SessionCollection"
     },
+    {
+      "kind": "mcp",
+      "name": "sessioncollection_findchildren",
+      "operation": "findChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
+    {
+      "kind": "mcp",
+      "name": "sessioncollection_revokechildren",
+      "operation": "revokeChildren",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
+    {
+      "kind": "mcp",
+      "name": "sessioncollection_revokeusersessionsbyauthmethod",
+      "operation": "revokeUserSessionsByAuthMethod",
+      "objectName": "@happyvertical/smrt-users:SessionCollection"
+    },
     {
       "kind": "mcp",
       "name": "sessioncollection_findvalidsession",
@@ -10146,6 +10796,30 @@
       "operation": "delete",
       "objectName": "@happyvertical/smrt-users:Session"
     },
+    {
+      "kind": "cli",
+      "name": "session_isLayered",
+      "operation": "isLayered",
+      "objectName": "@happyvertical/smrt-users:Session"
+    },
+    {
+      "kind": "cli",
+      "name": "session_getAbsoluteExpiry",
+      "operation": "getAbsoluteExpiry",
+      "objectName": "@happyvertical/smrt-users:Session"
+    },
+    {
+      "kind": "cli",
+      "name": "session_getIdleSeconds",
+      "operation": "getIdleSeconds",
+      "objectName": "@happyvertical/smrt-users:Session"
+    },
+    {
+      "kind": "cli",
+      "name": "session_getPermissionCeiling",
+      "operation": "getPermissionCeiling",
+      "objectName": "@happyvertical/smrt-users:Session"
+    },
     {
       "kind": "cli",
       "name": "session_isValid",
@@ -10579,19 +11253,19 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 25,
+    "foreignKeyFields": 26,
     "crossPackageRefFields": 1,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 90
+    "uuidColumns": 100
   },
-  "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/collections/CliAuthApproveLimitCollection.ts` | terminal approval concurrency, shared attempt budget, retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |\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. CLI remains a local-operator surface. Preserve the\n  registry assertions in `security-audit-1400.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- 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. `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",
+  "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/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. CLI remains a local-operator surface. Preserve the\n  registry assertions in `security-audit-1400.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- `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- 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": [
     {
       "path": "agents/permissions.md",
       "module": "permissions",
-      "content": "# Permissions and tenant inheritance\n\nRead for `src/services/PermissionResolver.ts`, operation guards, role seeding,\nRLS, and tenant-hierarchy changes. Integration examples live in README's\nmanifest-derived permission catalog and PostgreSQL RLS sections.\n\n## Membership selection\n\n1. A direct target-tenant membership pins resolution: active resolves normally;\n   pending/suspended returns empty. Never union direct and ancestor roles.\n2. Otherwise walk hierarchyPath nearest-first for the nearest active ancestor\n   membership whose role has inheritsToDescendants. Skip inactive/unflagged\n   ancestors; they neither grant nor block. No qualifying ancestor means empty.\n3. Run later layers against the target tenant. Only target-tenant groups apply;\n   membership overrides travel with the chosen ancestor membership.\n   inheritedFromTenantId reports that ancestor, null for direct resolution.\n\nVerify hierarchyPath link-by-link against loaded parentTenantId rows before\ntrusting it: excess depth, self-reference, duplicates or inconsistent paths\nfail closed. Bound traversal by MAX_TENANT_HIERARCHY_DEPTH. Tenant status is not\nconsulted, matching direct resolution. Long-lived user/tenant caches must\ninvalidate ancestor membership changes and inheritsToDescendants flips;\nrequest-scoped caches do not survive those requests.\n\n`loadSessionContext().tenantAuthorization` is authoritative for required-tenant\nconsumers; membership null can mean inherited authority.\n\n4. If no membership resolved at all, apply the opt-in ancestor-read policy\n   (smrt#2939): the user's ACTIVE memberships on VERIFIED DESCENDANTS of the\n   target, whose role slug is declared in `permissions.ancestorRead.roles` and\n   within `maxDepth` hops, contribute `<collection>.read` for declared\n   collections, intersected with BOTH that role's own catalog grants (so a\n   descendant-side tenant GRANT, group role, or membership GRANT cannot widen\n   it) AND the principal's effective permissions in that descendant (so its\n   DENY cascade and membership DENY apply). Only a SYSTEM\n   role (`tenantId` null, `isSystem: true`) matches a declared slug: slugs are\n   not unique across a hierarchy, so a tenant-scoped custom role of the same\n   name must not opt its tenant in. Off by default;\n   read-only; never lateral; never reached when a direct or inherited\n   membership already decided. The target tenant's DENY still subtracts.\n   `ancestorReadFromTenantIds` reports the contributing descendants. The grant\n   carries no membership, so `membershipId`/`tenantAuthorization.membershipId`\n   stay null and a consumer requiring a non-empty membership still refuses.\n\n## Permission precedence\n\nApply these layers in order, later layers overriding earlier ones:\n\n1. Ancestor TenantPermissionOverride cascade (GRANT adds, DENY removes).\n2. Selected membership role permissions.\n3. Target-tenant group-role permissions.\n4. Tenant cascade's net DENY removes role/group grants.\n5. Membership GRANT may re-add a tenant-denied slug.\n6. Membership DENY removes last and always wins.\n\nThe tenant block is the cascade's net result, not the union of historical DENYs:\na child's more-specific GRANT can override a parent DENY. Use a direct child\nmembership or tenant DENY to attenuate inherited role authority.\n`getGroupIdsForTenant(userId, tenantId)` is required; getGroupIds is cross-tenant.\n\n## Hierarchies and seeding\n\n- `Tenant.save()` derives hierarchyPath/hierarchyLevel from the REAL\n  parentTenantId chain on every save (never from an ancestor's stored path),\n  refuses missing parents, cycles and over-depth before writing, and\n  re-materializes descendants by raw column update (so STI subclass columns\n  are never clobbered). createChild/moveToParent/makeRoot are thin wrappers.\n  `materializeTenantHierarchy(db, { dryRun })` / `smrt\n  db:materialize-tenant-hierarchy` backfills legacy rows: idempotent, one\n  transaction, refuses a broken chain without writing (#3036). A NEW or\n  CHANGED parent link is authority-bearing, so `Tenant.save()` first loads the\n  parent through TenantCollection (the caller's tenancy scope) and refuses an\n  invisible one on every path — helpers, `create({ parentTenantId })`, or a\n  plain assignment + save; system context bypasses as usual, and an unchanged\n  link is never re-checked. getTree(rootId?)\n  returns UI structure. Maximum depth is 10.\n- Tenant override cascade requires parent cascadePermissions and child\n  inheritPermissions. These flags do not gate the independent, per-role\n  inheritsToDescendants membership flow.\n- `permissions.ancestorRead` in the `users` package config declares upward,\n  read-only visibility: `{ roles, collections, maxDepth? }`. Both lists are\n  required and non-empty and `maxDepth >= 1`, else the policy is OFF — there is\n  no partially valid declaration. `isAncestorReadableSlug()` is the single place\n  the read-only bound is enforced; only a two-segment `<collection>.<action>`\n  slug whose action normalizes to `read` on a declared collection passes.\n  `PermissionResolver.create(options, { ancestorReadPolicy })` binds one\n  resolver; `null` forces it off. It grants the OPERATION at the ancestor, never\n  row visibility — sibling rows stay scoped by the tenancy interceptor and RLS.\n- seedSystemRoles({ inheritsToDescendants: ['owner', 'admin'] }) flags listed\n  slugs additively, never unflags omitted ones, and rejects unknown slugs.\n  Default seeds are exact-tenant.\n- RolePermissionCollection.seedRolePermissions() or\n  seedSystemRoles({ seedPermissions: true }) maps owner/admin to all catalog\n  permissions, member to ordinary-resource read/create, viewer to read. Member\n  create excludes identity/RBAC/security resources and their joins/overrides.\n  Seeding is additive/idempotent; removal requires prune: true.\n- When a package adds built-in self-personalization permissions after role\n  creation, explicitly call seedDefaultRolePersonalizationPermissions(). It\n  upgrades owner/admin/member/viewer idempotently and never grants custom roles.\n\n## Guards and RLS\n\nPermissionCatalogService derives collection.action slugs from manifests,\nincluding custom actions; list/get map to read. Guards derive a class's slug\nthrough the same resolution (explicit `collection`, manifest entry, then its\nSTI base's), so an STI subtype resolves its STI base's collection\n(`Network extends Tenant` -> `tenants.update`) in every build, including a\nbundle decorated before its manifest loads (#3125). Hand-written mutations in form\nhandlers, endpoints, CLI and jobs use assertOperationPermission(). It requires\ncatalog presence then resolves permissions, throwing fail-closed by default.\nUse onDeny: 'return', checkOperationPermission or hasOperationPermission only\nwhen the caller handles a structured/boolean denial.\n\nGenerated SvelteKit write routes (POST/PUT/PATCH/DELETE CRUD and mutating\ncustom actions) enforce the same `collection.action` slug (custom actions use\n`collection.<method>`; actions hosted on a collection class use the item collection, which the catalog now emits) after authentication: the slug must be in the request's\nsession permission snapshot (`locals.permissions`/`permissionSet`/\n`smrtPermissions` or `locals.tenantContext.permissions`), otherwise 403. Only\n`locals.tenantContext.superAdminBypass` skips it; `api.public: true` stays open.\n\nResource-anchored guards receive the resource tenant ID. When it differs from\nthe session tenant, omit the session membership so the resolver selects the\nappropriate authority; mismatched supplied membership/tenant fails closed.\nInherited root-admin authority can then authorize descendant resources without\napplication-side membership fan-out.\n\nResolution cost must not scale with catalog size in objects (#3047): role →\npermission ids and ids → slugs are `list({ select })` projection reads (the\ncollections' beforeList interceptors still run; no RolePermission/Permission\nis hydrated), so an owner mapped to the whole catalog costs two queries and\nno per-permission objects. Keep new resolver reads projections when only ids\nor slugs are needed, and do not add public collection methods for them — each\nbecomes a custom-action slug in the manifest-derived catalog. The resolver's\ncollections never inherit `defaultListLimit`/`maxListLimit` from the caller's\noptions, and id-list reads chunk at `IN_LIST_CHUNK_SIZE` with an explicit\nlimit: a truncated authorization read would narrow the result silently.\n`issue-3047-permission-resolution-cost-postgres.test.ts` pins the hydration\nbudget and a golden equivalence matrix recorded on the hydrating resolver.\n\nThe same rule holds for every framework-internal authorization read (#3048):\ncollections that back a decision — the resolver's, the ResourceGrant exact-tuple\nread in `checkResourceOperationPermission()` (DENY wins only if every row is\nread), and TenantService's owned-tenant quota count — are created through\n`withoutListBounds()` (`src/services/authorization-read-options.ts`), which\nstrips only the caller's list bounds. Use it for any new decision read;\n`issue-3048-authorization-list-bounds-postgres.test.ts` pins it.\n\nPermissionResolver runs every resolution inside smrt-tenancy's system context\n(#3036). Its reads are deliberately cross-tenant and framework-owned — the\nancestor TenantPermissionOverride batch, ancestor memberships for\ninheritsToDescendants, descendant memberships for ancestor-read — and are keyed\nby the explicit (userId, tenantId); with those classes registered tenant-scoped\n(`autoFilter`) the consumer's filter otherwise threw TenantIsolationError or\nsilently narrowed them. It returns slugs and ids only, never rows, and the\ncaller's own reads stay filtered. Do not move a resolver read back under the\nambient tenant; the Postgres regression suite\n`issue-3036-hierarchy-resolution-postgres.test.ts` pins this. Because nothing\nbackstops those reads any more, the tenant-override cascade verifies its chain\ntoo: it uses hierarchyPath only when it agrees link-by-link with\nparentTenantId, otherwise walks the real parent links (so a forged path cannot\ncascade an unrelated tenant in, and a never-materialized row still gets its real\nancestors' DENYs — and GRANTs), and throws TenantHierarchyError on a broken\nreal chain: a per-request failure for that tenant's whole subtree, which\n`smrt db:materialize-tenant-hierarchy --dry-run` reports ahead of time (see\nREADME \"Upgrading an existing fleet\").\n`getTenantInheritanceChain()` returns Tenant rows, so it is NOT run in system\ncontext; it reports the same verified chain the cascade applies when the\ncaller can read every ancestor. Otherwise it never reports PARENT_NOT_FOUND\nfor a row the caller simply cannot see: an interceptor refusal surfaces as\nTenantIsolationError, and a silently filtered row (e.g. RLS) ends the chain at\nthe nearest readable ancestor. Descendant path rewrites are raw column updates recorded through\n`bumpChangeFeed`; `updated_at` is intentionally not bumped (derived columns;\nevery save recomputes them). They are not atomic with the moving row's save —\nan interrupted subtree fails closed until re-saved or backfilled.\n\nSystem context and super-admin bypass are honored. Pass\nallowSuperAdminBypass: false for money or separation-of-duties operations that\nrequire an explicit grant.\n\ngeneratePostgresPermissionSql/applyPostgresPermissionPolicies enforce generated\nRLS using smrt.permissions and smrt.tenant_id, installed with set_config by\nwithSessionPermissionContext. This bounds REST, MCP and in-process database\naccess once principal context is set. Child-tenant sessions receive resolved\ninherited permissions automatically, but RLS row filtering remains bound to the\nsession tenant: a root session's app-level guard authorization does not itself\npermit child rows through RLS. Preserve this distinction.\n"
+      "content": "# Permissions and tenant inheritance\n\nRead for `src/services/PermissionResolver.ts`, operation guards, role seeding,\nRLS, and tenant-hierarchy changes. Integration examples live in README's\nmanifest-derived permission catalog and PostgreSQL RLS sections.\n\n## Membership selection\n\n1. A direct target-tenant membership pins resolution: active resolves normally;\n   pending/suspended returns empty. Never union direct and ancestor roles.\n2. Otherwise walk hierarchyPath nearest-first for the nearest active ancestor\n   membership whose role has inheritsToDescendants. Skip inactive/unflagged\n   ancestors; they neither grant nor block. No qualifying ancestor means empty.\n3. Run later layers against the target tenant. Only target-tenant groups apply;\n   membership overrides travel with the chosen ancestor membership.\n   inheritedFromTenantId reports that ancestor, null for direct resolution.\n\nVerify hierarchyPath link-by-link against loaded parentTenantId rows before\ntrusting it: excess depth, self-reference, duplicates or inconsistent paths\nfail closed. Bound traversal by MAX_TENANT_HIERARCHY_DEPTH. Tenant status is not\nconsulted, matching direct resolution. Long-lived user/tenant caches must\ninvalidate ancestor membership changes and inheritsToDescendants flips;\nrequest-scoped caches do not survive those requests.\n\n`loadSessionContext().tenantAuthorization` is authoritative for required-tenant\nconsumers; membership null can mean inherited authority.\n\n4. If no membership resolved at all, apply the opt-in ancestor-read policy\n   (smrt#2939): the user's ACTIVE memberships on VERIFIED DESCENDANTS of the\n   target, whose role slug is declared in `permissions.ancestorRead.roles` and\n   within `maxDepth` hops, contribute `<collection>.read` for declared\n   collections, intersected with BOTH that role's own catalog grants (so a\n   descendant-side tenant GRANT, group role, or membership GRANT cannot widen\n   it) AND the principal's effective permissions in that descendant (so its\n   DENY cascade and membership DENY apply). Only a SYSTEM\n   role (`tenantId` null, `isSystem: true`) matches a declared slug: slugs are\n   not unique across a hierarchy, so a tenant-scoped custom role of the same\n   name must not opt its tenant in. Off by default;\n   read-only; never lateral; never reached when a direct or inherited\n   membership already decided. The target tenant's DENY still subtracts.\n   `ancestorReadFromTenantIds` reports the contributing descendants. The grant\n   carries no membership, so `membershipId`/`tenantAuthorization.membershipId`\n   stay null and a consumer requiring a non-empty membership still refuses.\n\n## Permission precedence\n\nApply these layers in order, later layers overriding earlier ones:\n\n1. Ancestor TenantPermissionOverride cascade (GRANT adds, DENY removes).\n2. Selected membership role permissions.\n3. Target-tenant group-role permissions.\n4. Tenant cascade's net DENY removes role/group grants.\n5. Membership GRANT may re-add a tenant-denied slug.\n6. Membership DENY removes last and always wins.\n\nThe tenant block is the cascade's net result, not the union of historical DENYs:\na child's more-specific GRANT can override a parent DENY. Use a direct child\nmembership or tenant DENY to attenuate inherited role authority.\n`getGroupIdsForTenant(userId, tenantId)` is required; getGroupIds is cross-tenant.\n\n## Hierarchies and seeding\n\n- `Tenant.save()` derives hierarchyPath/hierarchyLevel from the REAL\n  parentTenantId chain on every save (never from an ancestor's stored path),\n  refuses missing parents, cycles and over-depth before writing, and\n  re-materializes descendants by raw column update (so STI subclass columns\n  are never clobbered). createChild/moveToParent/makeRoot are thin wrappers.\n  `materializeTenantHierarchy(db, { dryRun })` / `smrt\n  db:materialize-tenant-hierarchy` backfills legacy rows: idempotent, one\n  transaction, refuses a broken chain without writing (#3036). A NEW or\n  CHANGED parent link is authority-bearing, so `Tenant.save()` first loads the\n  parent through TenantCollection (the caller's tenancy scope) and refuses an\n  invisible one on every path — helpers, `create({ parentTenantId })`, or a\n  plain assignment + save; system context bypasses as usual, and an unchanged\n  link is never re-checked. getTree(rootId?)\n  returns UI structure. Maximum depth is 10.\n- Tenant override cascade requires parent cascadePermissions and child\n  inheritPermissions. These flags do not gate the independent, per-role\n  inheritsToDescendants membership flow.\n- `permissions.ancestorRead` in the `users` package config declares upward,\n  read-only visibility: `{ roles, collections, maxDepth? }`. Both lists are\n  required and non-empty and `maxDepth >= 1`, else the policy is OFF — there is\n  no partially valid declaration. `isAncestorReadableSlug()` is the single place\n  the read-only bound is enforced; only a two-segment `<collection>.<action>`\n  slug whose action normalizes to `read` on a declared collection passes.\n  `PermissionResolver.create(options, { ancestorReadPolicy })` binds one\n  resolver; `null` forces it off. It grants the OPERATION at the ancestor, never\n  row visibility — sibling rows stay scoped by the tenancy interceptor and RLS.\n- seedSystemRoles({ inheritsToDescendants: ['owner', 'admin'] }) flags listed\n  slugs additively, never unflags omitted ones, and rejects unknown slugs.\n  Default seeds are exact-tenant.\n- RolePermissionCollection.seedRolePermissions() or\n  seedSystemRoles({ seedPermissions: true }) maps owner/admin to all catalog\n  permissions, member to ordinary-resource read/create, viewer to read. Member\n  create excludes identity/RBAC/security resources and their joins/overrides.\n  Seeding is additive/idempotent; removal requires prune: true. Catalog sync\n  and grants plan from one read, then commit in `SEEDING_BATCH_SIZE` batches\n  (#3323): never one durable commit per row (an fsync each on local SQLite),\n  and never one catalog-wide transaction (`@happyvertical/sql` transaction\n  scopes cost superlinearly per statement). Pass a caller transaction's handle.\n- When a package adds built-in self-personalization permissions after role\n  creation, explicitly call seedDefaultRolePersonalizationPermissions(). It\n  upgrades owner/admin/member/viewer idempotently and never grants custom roles.\n\n## Guards and RLS\n\nPermissionCatalogService derives collection.action slugs from manifests,\nincluding custom actions; list/get map to read. Guards derive a class's slug\nthrough the same resolution (explicit `collection`, manifest entry, then its\nSTI base's), so an STI subtype resolves its STI base's collection\n(`Network extends Tenant` -> `tenants.update`) in every build, including a\nbundle decorated before its manifest loads (#3125). Hand-written mutations in form\nhandlers, endpoints, CLI and jobs use assertOperationPermission(). It requires\ncatalog presence then resolves permissions, throwing fail-closed by default.\nUse onDeny: 'return', checkOperationPermission or hasOperationPermission only\nwhen the caller handles a structured/boolean denial.\n\nGenerated SvelteKit write routes (POST/PUT/PATCH/DELETE CRUD and mutating\ncustom actions) enforce the same `collection.action` slug (custom actions use\n`collection.<method>`; actions hosted on a collection class use the item collection, which the catalog now emits) after authentication: the slug must be in the request's\nsession permission snapshot (`locals.permissions`/`permissionSet`/\n`smrtPermissions` or `locals.tenantContext.permissions`), otherwise 403. Only\n`locals.tenantContext.superAdminBypass` skips it; `api.public: true` stays open.\n\nResource-anchored guards receive the resource tenant ID. When it differs from\nthe session tenant, omit the session membership so the resolver selects the\nappropriate authority; mismatched supplied membership/tenant fails closed.\nInherited root-admin authority can then authorize descendant resources without\napplication-side membership fan-out.\n\nResolution cost must not scale with catalog size in objects (#3047): role →\npermission ids and ids → slugs are `list({ select })` projection reads (the\ncollections' beforeList interceptors still run; no RolePermission/Permission\nis hydrated), so an owner mapped to the whole catalog costs two queries and\nno per-permission objects. Keep new resolver reads projections when only ids\nor slugs are needed, and do not add public collection methods for them — each\nbecomes a custom-action slug in the manifest-derived catalog. The resolver's\ncollections never inherit `defaultListLimit`/`maxListLimit` from the caller's\noptions, and id-list reads chunk at `IN_LIST_CHUNK_SIZE` with an explicit\nlimit: a truncated authorization read would narrow the result silently.\n`issue-3047-permission-resolution-cost-postgres.test.ts` pins the hydration\nbudget and a golden equivalence matrix recorded on the hydrating resolver.\n\nThe same rule holds for every framework-internal authorization read (#3048):\ncollections that back a decision — the resolver's, the ResourceGrant exact-tuple\nread in `checkResourceOperationPermission()` (DENY wins only if every row is\nread), and TenantService's owned-tenant quota count — are created through\n`withoutListBounds()` (`src/services/authorization-read-options.ts`), which\nstrips only the caller's list bounds. Use it for any new decision read;\n`issue-3048-authorization-list-bounds-postgres.test.ts` pins it.\n\nPermissionResolver runs every resolution inside smrt-tenancy's system context\n(#3036). Its reads are deliberately cross-tenant and framework-owned — the\nancestor TenantPermissionOverride batch, ancestor memberships for\ninheritsToDescendants, descendant memberships for ancestor-read — and are keyed\nby the explicit (userId, tenantId); with those classes registered tenant-scoped\n(`autoFilter`) the consumer's filter otherwise threw TenantIsolationError or\nsilently narrowed them. It returns slugs and ids only, never rows, and the\ncaller's own reads stay filtered. Do not move a resolver read back under the\nambient tenant; the Postgres regression suite\n`issue-3036-hierarchy-resolution-postgres.test.ts` pins this. Because nothing\nbackstops those reads any more, the tenant-override cascade verifies its chain\ntoo: it uses hierarchyPath only when it agrees link-by-link with\nparentTenantId, otherwise walks the real parent links (so a forged path cannot\ncascade an unrelated tenant in, and a never-materialized row still gets its real\nancestors' DENYs — and GRANTs), and throws TenantHierarchyError on a broken\nreal chain: a per-request failure for that tenant's whole subtree, which\n`smrt db:materialize-tenant-hierarchy --dry-run` reports ahead of time (see\nREADME \"Upgrading an existing fleet\").\n`getTenantInheritanceChain()` returns Tenant rows, so it is NOT run in system\ncontext; it reports the same verified chain the cascade applies when the\ncaller can read every ancestor. Otherwise it never reports PARENT_NOT_FOUND\nfor a row the caller simply cannot see: an interceptor refusal surfaces as\nTenantIsolationError, and a silently filtered row (e.g. RLS) ends the chain at\nthe nearest readable ancestor. Descendant path rewrites are raw column updates recorded through\n`bumpChangeFeed`; `updated_at` is intentionally not bumped (derived columns;\nevery save recomputes them). They are not atomic with the moving row's save —\nan interrupted subtree fails closed until re-saved or backfilled.\n\nSystem context and super-admin bypass are honored. Pass\nallowSuperAdminBypass: false for money or separation-of-duties operations that\nrequire an explicit grant.\n\ngeneratePostgresPermissionSql/applyPostgresPermissionPolicies enforce generated\nRLS using smrt.permissions and smrt.tenant_id, installed with set_config by\nwithSessionPermissionContext. This bounds REST, MCP and in-process database\naccess once principal context is set. Child-tenant sessions receive resolved\ninherited permissions automatically, but RLS row filtering remains bound to the\nsession tenant: a root session's app-level guard authorization does not itself\npermit child rows through RLS. Preserve this distinction.\n\nRolePermission's natural key is `(role_id, permission_id)` (#3329); repeated or\nconcurrent inserts converge without changing the grant ID. Existing deployments\nmust run `deduplicateRolePermissions()` with stopped writers before ordinary\nschema migration; see README's \"Upgrade duplicate role grants\". It keeps the\noldest row and installs uniqueness atomically. Runtime seeding never performs\nthis schema repair.\n"
     },
     {
       "path": "agents/oidc-provisioning.md",
@@ -10611,7 +11285,7 @@
     {
       "path": "agents/retention.md",
       "module": "retention",
-      "content": "# smrt-users/credential retention\n\nModule semantics for `src/retention.ts` and the three `deleteExpired()` paths\nit drives. Package orientation, the permission model, and the security rules\nthat apply before editing anything live in [../AGENTS.md](../AGENTS.md) — read\nthat first.\n\n## Credential retention (#2375)\n\n`SessionCollection.deleteExpired()`,\n`UsersMagicLinkTokenCollection.deleteExpired()` and\n`UsersCliAuthRequestCollection.deleteExpired()` all existed, and all waited for\nan application to remember to call them. Expired credential rows are the worst\nkind of unbounded growth: worthless the moment they expire, and exactly the\nrows an attacker would like to still find in the table.\n\n`src/retention.ts` contributes the three to the framework retention sweep in\n`@happyvertical/smrt-core`, so `smrt db:prune` and a running jobs `TaskRunner`\nreap them.\n\n- **The entry point registers on import.** `src/index.ts` calls\n  `registerUserRetentionTasks()`, so any process that loaded this package\n  contributes the tasks — including `smrt db:prune`, which imports the package\n  optionally for exactly that reason. Registering is not scheduling: nothing is\n  deleted until something runs a sweep.\n- **Task names** are `users-sessions`, `users-magic-link-tokens`,\n  `users-cli-auth-requests` — prefixed with the package's short name because\n  the retention registry is one process-global namespace. Opt one out with\n  `runRetentionSweep(db, { tasks: { 'users-sessions': false } })` or\n  `smrt db:prune --skip users-sessions`; `unregisterUserRetentionTasks()`\n  removes all three.\n- **There is no retention window to configure.** An expired credential has\n  nothing worth retaining, so each task deletes only already-expired rows. An\n  application that keeps expired sessions for audit should opt the task out and\n  archive them itself.\n- **All three are a single counted DELETE**, not a hydrate-and-delete loop.\n  They now run unattended on a timer, and a per-row delete that throws part-way\n  leaves the rest of the expired rows un-reaped — the #1400 reasoning that\n  already applied to sessions, now applied to the other two. Counting first\n  also gives a usable figure where `rowCount` is not populated, and is what\n  makes `{ dryRun }` preview the same predicate rather than an estimate. The\n  count and the delete are not one transaction, so the figure is approximate\n  under concurrent writers.\n- **`expiresAt` is `@field({ indexed: true })`** on `Session`,\n  `UsersMagicLinkToken` and `UsersCliAuthRequest`: the prune predicate scans\n  that column on every pass.\n- **CLI bearer handoff is single-use.** An approved request becomes `consumed`\n  and clears its `sessionId` when one poller wins the exchange. The CLI\n  retention task deletes pending requests past their TTL, requests already\n  marked `expired` by lazy expiry, and consumed history; it retains approved\n  requests until exchange so a near-expiry approval cannot orphan its bearer\n  session.\n"
+      "content": "# smrt-users/credential retention\n\nModule semantics for `src/retention.ts` and the three `deleteExpired()` paths\nit drives. Package orientation, the permission model, and the security rules\nthat apply before editing anything live in [../AGENTS.md](../AGENTS.md) — read\nthat first.\n\n## Credential retention (#2375)\n\n`SessionCollection.deleteExpired()`,\n`UsersMagicLinkTokenCollection.deleteExpired()` and\n`UsersCliAuthRequestCollection.deleteExpired()` all existed, and all waited for\nan application to remember to call them. Expired credential rows are the worst\nkind of unbounded growth: worthless the moment they expire, and exactly the\nrows an attacker would like to still find in the table.\n\n`src/retention.ts` contributes the three to the framework retention sweep in\n`@happyvertical/smrt-core`, so `smrt db:prune` and a running jobs `TaskRunner`\nreap them.\n\n- **The entry point registers on import.** `src/index.ts` calls\n  `registerUserRetentionTasks()`, so any process that loaded this package\n  contributes the tasks — including `smrt db:prune`, which imports the package\n  optionally for exactly that reason. Registering is not scheduling: nothing is\n  deleted until something runs a sweep.\n- **Task names** are `users-sessions`, `users-magic-link-tokens`,\n  `users-cli-auth-requests`, `users-login-attempts`, `users-login-audit-events`\n  — prefixed with the package's short name because the retention registry is\n  one process-global namespace. Opt one out with\n  `runRetentionSweep(db, { tasks: { 'users-sessions': false } })` or\n  `smrt db:prune --skip users-sessions`; `unregisterUserRetentionTasks()`\n  removes all of them.\n- **The credential tasks have no retention window to configure.** An expired\n  credential has nothing worth retaining, so each deletes only already-expired\n  rows. An application that keeps expired sessions for audit should opt the\n  task out and archive them itself. The two #3273 tasks differ: limiter rows\n  are pruned once past their own `retain_until` — written by the limiter from\n  its configured window and streak-forgiveness horizon, so a custom-configured\n  limiter is never swept early — and never while a lockout is live; audit\n  events are pruned after\n  `DEFAULT_LOGIN_AUDIT_RETENTION_DAYS` (90). A host that needs longer audit\n  retention opts `users-login-audit-events` out and archives.\n- **All three are a single counted DELETE**, not a hydrate-and-delete loop.\n  They now run unattended on a timer, and a per-row delete that throws part-way\n  leaves the rest of the expired rows un-reaped — the #1400 reasoning that\n  already applied to sessions, now applied to the other two. Counting first\n  also gives a usable figure where `rowCount` is not populated, and is what\n  makes `{ dryRun }` preview the same predicate rather than an estimate. The\n  count and the delete are not one transaction, so the figure is approximate\n  under concurrent writers.\n- **`expiresAt` is `@field({ indexed: true })`** on `Session`,\n  `UsersMagicLinkToken` and `UsersCliAuthRequest`: the prune predicate scans\n  that column on every pass.\n- **CLI bearer handoff is single-use.** An approved request becomes `consumed`\n  and clears its `sessionId` when one poller wins the exchange. The CLI\n  retention task deletes pending requests past their TTL, requests already\n  marked `expired` by lazy expiry, and consumed history; it retains approved\n  requests until exchange so a near-expiry approval cannot orphan its bearer\n  session.\n"
     }
   ]
 }