@happyvertical/smrt-users 0.53.3 → 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.53.3",
+  "packageVersion": "0.53.5",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "e02aa504efea9b27f5f4c350a10a02d6c365b20f02e7dfd7fae30c9a416832db",
-    "packageJson": "78927ee5ef09e43afc1824bb6233d31ad314275ca678c66cbeb011e97b652b31",
-    "agents": "c1bd1dcae5f1662f31d01d0cff19cb3f774715eb71ecfd249eb429e5f64a3eb7",
+    "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",
@@ -5796,6 +6304,12 @@
           "required": false,
           "columnType": "JSON",
           "default": {}
+        },
+        {
+          "name": "authMethod",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         }
       ],
       "relationships": [
@@ -5816,8 +6330,12 @@
       ],
       "methods": [
         "extend",
+        "getAbsoluteExpiry",
         "getData",
+        "getIdleSeconds",
+        "getPermissionCeiling",
         "isExpired",
+        "isLayered",
         "isRevoked",
         "isValid",
         "recordActivity",
@@ -5835,6 +6353,10 @@
           ],
           "returns": "void"
         },
+        {
+          "name": "getAbsoluteExpiry",
+          "returns": "Date | null"
+        },
         {
           "name": "getData",
           "params": [
@@ -5842,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"
@@ -5946,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",
@@ -6021,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",
@@ -6028,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",
@@ -6035,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",
@@ -8404,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",
@@ -8498,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",
@@ -8570,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",
@@ -10150,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",
@@ -10583,14 +11253,14 @@
   ],
   "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",
@@ -10615,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"
     }
   ]
 }