@happyvertical/smrt-users 0.55.18 → 0.55.19

package/dist/smrt-knowledge.json

@@ -3,18 +3,18 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-users",
-  "packageVersion": "0.55.18",
+  "packageVersion": "0.55.19",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "ab8b58873ab1fd02a7b11f4f10101fdaffee736de6ba9959f31365f70cb7afc9",
-    "packageJson": "b45c8f57c3c100ccc7b41757c7e3d085b59390a67b1004b764a4681e10d6f955",
+    "manifest": "76d9496f05f791bfd683b74ce6e73943c80c812aefb14bb9db66ce7d321386af",
+    "packageJson": "ea75194d38a17533bbdab1fdbdaa5b251b913168d1ece5f982fb35717b2b1373",
     "agents": "eb74cdf8186c27e8721515cff653c688567284015ce9845a9b7714ac898620bc",
     "moduleDoc:agents/permissions.md": "832a684513d831d3cb9bd8d0c73295d756ca7cf9bc32de1ca3254691160371b1",
     "moduleDoc:agents/oidc-provisioning.md": "b73f3fdaf61136720132a614c7e14237b7bd35f7bf5d43eabb29f565485803b9",
     "moduleDoc:agents/mobile-auth.md": "25e85e83f43e3a46383a92fa809f3a003b4545c3026e78dbe1bccbbc35161e18",
     "moduleDoc:agents/terminal-auth-testing.md": "8a84c16a19e381427aed81d3b1882344c427fe22a70e87f5ac2db836b1a6822d",
-    "moduleDoc:agents/retention.md": "073874bf16ce3fbbc503157679dc7fe69800fb39a59e40299bcc713f099bf3d8"
+    "moduleDoc:agents/retention.md": "99fb97718347e06ae3d886718aec5ec1ae8cb2d312b8ac79de2609821d230a35"
   },
   "exports": [
     ".",
@@ -26,6 +26,7 @@
     "./sveltekit"
   ],
   "dependencies": {
+    "@happyvertical/auth": "catalog:",
     "@happyvertical/logger": "catalog:",
     "@happyvertical/smrt-config": "workspace:*",
     "@happyvertical/smrt-core": "workspace:*",
@@ -1650,6 +1651,302 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "UsersOAuthClientCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthClientCollection",
+      "collection": "usersoauthclients",
+      "tableName": "users_oauth_clients",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByClientId"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByClientId",
+          "params": [
+            "clientId: string"
+          ],
+          "returns": "Promise<UsersOAuthClient | null>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "usersoauthclients.findByClientId",
+          "operation": "findByClientId",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthClientCollection",
+          "path": "/usersoauthclients/findByClientId",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthclientcollection_findbyclientid",
+          "operation": "findByClientId",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthClientCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAuthorizationCodeCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCodeCollection",
+      "collection": "usersoauthauthorizationcodes",
+      "tableName": "users_oauth_authorization_codes",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "consume"
+      ],
+      "methodSignatures": [
+        {
+          "name": "consume",
+          "async": true,
+          "params": [
+            "id: string",
+            "codeHash: string",
+            "clientId: string",
+            "redirectUri: string",
+            "resource: string | null",
+            "now: Date"
+          ],
+          "returns": "Promise<boolean>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "usersoauthauthorizationcodes.consume",
+          "operation": "consume",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCodeCollection",
+          "path": "/usersoauthauthorizationcodes/consume",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthauthorizationcodecollection_consume",
+          "operation": "consume",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCodeCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthRefreshGrantCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection",
+      "collection": "usersoauthrefreshgrants",
+      "tableName": "users_oauth_refresh_grants",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "consume",
+        "revokeFamily"
+      ],
+      "methodSignatures": [
+        {
+          "name": "consume",
+          "async": true,
+          "params": [
+            "id: string",
+            "tokenHash: string",
+            "clientId: string",
+            "resource: string | null",
+            "now: Date"
+          ],
+          "returns": "Promise<boolean>"
+        },
+        {
+          "name": "revokeFamily",
+          "async": true,
+          "params": [
+            "familyId: string",
+            "now: Date"
+          ],
+          "returns": "Promise<void>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "usersoauthrefreshgrants.consume",
+          "operation": "consume",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection",
+          "path": "/usersoauthrefreshgrants/consume",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "usersoauthrefreshgrants.revokeFamily",
+          "operation": "revokeFamily",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection",
+          "path": "/usersoauthrefreshgrants/revokeFamily",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthrefreshgrantcollection_consume",
+          "operation": "consume",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthrefreshgrantcollection_revokefamily",
+          "operation": "revokeFamily",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAccessTokenRevocationCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocationCollection",
+      "collection": "usersoauthaccesstokenrevocations",
+      "tableName": "users_oauth_access_token_revocations",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByJti"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByJti",
+          "async": true,
+          "params": [
+            "jti: string"
+          ],
+          "returns": "Promise<UsersOAuthAccessTokenRevocation | null>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "usersoauthaccesstokenrevocations.findByJti",
+          "operation": "findByJti",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocationCollection",
+          "path": "/usersoauthaccesstokenrevocations/findByJti",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthaccesstokenrevocationcollection_findbyjti",
+          "operation": "findByJti",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocationCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAuthorizationCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCollection",
+      "collection": "usersoauthauthorizations",
+      "description": "Consent storage is intentionally inaccessible through generated surfaces.",
+      "tableName": "users_oauth_authorizations",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthRefreshFamilyCollection",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection",
+      "collection": "usersoauthrefreshfamilies",
+      "description": "Family rows exist for the entire lifetime of every descendant refresh token.",
+      "tableName": "users_oauth_refresh_families",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "lock",
+        "revoke"
+      ],
+      "methodSignatures": [
+        {
+          "name": "lock",
+          "async": true,
+          "params": [
+            "id: string",
+            "now: Date"
+          ],
+          "returns": "Promise<boolean>"
+        },
+        {
+          "name": "revoke",
+          "async": true,
+          "params": [
+            "id: string",
+            "now: Date"
+          ],
+          "returns": "Promise<void>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "usersoauthrefreshfamilies.lock",
+          "operation": "lock",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection",
+          "path": "/usersoauthrefreshfamilies/lock",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "usersoauthrefreshfamilies.revoke",
+          "operation": "revoke",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection",
+          "path": "/usersoauthrefreshfamilies/revoke",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthrefreshfamilycollection_lock",
+          "operation": "lock",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection"
+        },
+        {
+          "kind": "mcp",
+          "name": "usersoauthrefreshfamilycollection_revoke",
+          "operation": "revoke",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "UsersPasswordCredentialCollection",
       "qualifiedName": "@happyvertical/smrt-users:UsersPasswordCredentialCollection",
@@ -5381,71 +5678,553 @@
       "risks": []
     },
     {
-      "name": "UsersPasswordCredential",
-      "qualifiedName": "@happyvertical/smrt-users:UsersPasswordCredential",
-      "collection": "userspasswordcredentials",
-      "tableName": "users_password_credentials",
+      "name": "UsersOAuthClient",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthClient",
+      "collection": "usersoauthclients",
+      "tableName": "users_oauth_clients",
       "packageName": "@happyvertical/smrt-users",
       "extends": "SmrtObject",
       "fields": [
         {
-          "name": "userId",
-          "type": "foreignKey",
+          "name": "clientId",
+          "type": "text",
           "required": true,
-          "related": "User",
-          "columnType": "UUID"
+          "columnType": "TEXT"
         },
         {
-          "name": "version",
-          "type": "integer",
-          "required": true,
-          "columnType": "INTEGER",
-          "default": 1
+          "name": "redirectUris",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         },
         {
-          "name": "mustChange",
-          "type": "boolean",
-          "required": true,
-          "columnType": "BOOLEAN",
-          "default": false
+          "name": "allowedScopes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         },
         {
-          "name": "rotatedAt",
-          "type": "datetime",
+          "name": "tokenEndpointAuthMethod",
+          "type": "text",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TEXT",
+          "default": "none"
         },
         {
-          "name": "rotatedBy",
+          "name": "allowedResources",
           "type": "text",
           "required": false,
           "columnType": "TEXT"
+        },
+        {
+          "name": "createdAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
         }
       ],
-      "relationships": [
+      "relationships": [],
+      "methods": [
+        "getAllowedResources",
+        "getAllowedScopes",
+        "getRedirectUris"
+      ],
+      "methodSignatures": [
         {
-          "name": "userId",
-          "type": "foreignKey",
-          "required": true,
-          "related": "User",
-          "columnType": "UUID"
+          "name": "getAllowedResources",
+          "returns": "string[] | undefined"
+        },
+        {
+          "name": "getAllowedScopes",
+          "returns": "string[]"
+        },
+        {
+          "name": "getRedirectUris",
+          "returns": "string[]"
         }
       ],
-      "methods": [],
       "surfaces": [],
-      "relationshipFeatures": [
-        "foreignKey",
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "Permission",
-      "qualifiedName": "@happyvertical/smrt-users:Permission",
-      "displayLabelField": "name",
-      "collection": "permissions",
-      "description": "Permission represents a named capability in the system.",
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getAllowedResources",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthClient"
+        },
+        {
+          "kind": "api",
+          "operation": "getAllowedScopes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthClient"
+        },
+        {
+          "kind": "api",
+          "operation": "getRedirectUris",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthClient"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAuthorizationCode",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCode",
+      "collection": "usersoauthauthorizationcodes",
+      "tableName": "users_oauth_authorization_codes",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "authorizationId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "clientId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "subject",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "claims",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "redirectUri",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scopes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "resource",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "codeChallenge",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "consumedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getClaims",
+        "getScopes"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getClaims",
+          "returns": "OAuthTokenClaims"
+        },
+        {
+          "name": "getScopes",
+          "returns": "string[]"
+        }
+      ],
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getClaims",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCode"
+        },
+        {
+          "kind": "api",
+          "operation": "getScopes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCode"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthRefreshGrant",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthRefreshGrant",
+      "collection": "usersoauthrefreshgrants",
+      "tableName": "users_oauth_refresh_grants",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "authorizationId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "familyId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "clientId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "subject",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "claims",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scopes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "resource",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "consumedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "revokedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getClaims",
+        "getScopes"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getClaims",
+          "returns": "OAuthTokenClaims"
+        },
+        {
+          "name": "getScopes",
+          "returns": "string[]"
+        }
+      ],
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getClaims",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrant"
+        },
+        {
+          "kind": "api",
+          "operation": "getScopes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrant"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAccessTokenRevocation",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocation",
+      "collection": "usersoauthaccesstokenrevocations",
+      "tableName": "users_oauth_access_token_revocations",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthAuthorization",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthAuthorization",
+      "collection": "usersoauthauthorizations",
+      "description": "A consent decision bound to a server-side session; never exposes its bearer.",
+      "tableName": "users_oauth_authorizations",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "subject",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "clientId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scopes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "permissionCeiling",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "resource",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "revokedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "getPermissionCeiling",
+        "getScopes"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getPermissionCeiling",
+          "returns": "string[]"
+        },
+        {
+          "name": "getScopes",
+          "returns": "string[]"
+        }
+      ],
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getPermissionCeiling",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorization"
+        },
+        {
+          "kind": "api",
+          "operation": "getScopes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorization"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersOAuthRefreshFamily",
+      "qualifiedName": "@happyvertical/smrt-users:UsersOAuthRefreshFamily",
+      "collection": "usersoauthrefreshfamilies",
+      "description": "Stable lock row: rotation and revocation always serialize on this family.",
+      "tableName": "users_oauth_refresh_families",
+      "packageName": "@happyvertical/smrt-users",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "authorizationId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "revokedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UsersPasswordCredential",
+      "qualifiedName": "@happyvertical/smrt-users:UsersPasswordCredential",
+      "collection": "userspasswordcredentials",
+      "tableName": "users_password_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": "mustChange",
+          "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": "Permission",
+      "qualifiedName": "@happyvertical/smrt-users:Permission",
+      "displayLabelField": "name",
+      "collection": "permissions",
+      "description": "Permission represents a named capability in the system.",
       "tableName": "permissions",
       "packageName": "@happyvertical/smrt-users",
       "extends": "SmrtObject",
@@ -7968,6 +8747,104 @@
       "operation": "denyPermission",
       "objectName": "@happyvertical/smrt-users:MembershipOverrideCollection"
     },
+    {
+      "kind": "api",
+      "name": "usersoauthclients.findByClientId",
+      "operation": "findByClientId",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthClientCollection",
+      "path": "/usersoauthclients/findByClientId",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthclientcollection_findbyclientid",
+      "operation": "findByClientId",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthClientCollection"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthauthorizationcodes.consume",
+      "operation": "consume",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCodeCollection",
+      "path": "/usersoauthauthorizationcodes/consume",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthauthorizationcodecollection_consume",
+      "operation": "consume",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthAuthorizationCodeCollection"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthrefreshgrants.consume",
+      "operation": "consume",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection",
+      "path": "/usersoauthrefreshgrants/consume",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthrefreshgrants.revokeFamily",
+      "operation": "revokeFamily",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection",
+      "path": "/usersoauthrefreshgrants/revokeFamily",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthrefreshgrantcollection_consume",
+      "operation": "consume",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthrefreshgrantcollection_revokefamily",
+      "operation": "revokeFamily",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshGrantCollection"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthaccesstokenrevocations.findByJti",
+      "operation": "findByJti",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocationCollection",
+      "path": "/usersoauthaccesstokenrevocations/findByJti",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthaccesstokenrevocationcollection_findbyjti",
+      "operation": "findByJti",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthAccessTokenRevocationCollection"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthrefreshfamilies.lock",
+      "operation": "lock",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection",
+      "path": "/usersoauthrefreshfamilies/lock",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "usersoauthrefreshfamilies.revoke",
+      "operation": "revoke",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection",
+      "path": "/usersoauthrefreshfamilies/revoke",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthrefreshfamilycollection_lock",
+      "operation": "lock",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection"
+    },
+    {
+      "kind": "mcp",
+      "name": "usersoauthrefreshfamilycollection_revoke",
+      "operation": "revoke",
+      "objectName": "@happyvertical/smrt-users:UsersOAuthRefreshFamilyCollection"
+    },
     {
       "kind": "api",
       "name": "permissions.findByCategory",
@@ -9950,7 +10827,7 @@
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 104
+    "uuidColumns": 116
   },
   "agentDoc": "# @happyvertical/smrt-users\n\nMulti-tenant identity, RBAC, hierarchical tenants, sessions, and SvelteKit auth.\n\n## Modules\n\nRead only the module relevant to the change; protocol and provisioning details\nare not prerequisites for unrelated user-package work.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `src/services/PermissionResolver.ts` | permission precedence, inherited memberships, guards, RLS, role seeding | [agents/permissions.md](agents/permissions.md) |\n| `src/services/OidcLoginService.ts`, collections and OIDC handlers | identity reconciliation, transaction boundaries, migration readiness | [agents/oidc-provisioning.md](agents/oidc-provisioning.md) |\n| `src/services/MobileAuthService.ts` | mobile handshake, bearer sessions, bootstrap extension boundary | [agents/mobile-auth.md](agents/mobile-auth.md) |\n| `src/services/TerminalAuthService.ts`, `src/services/LoginAttemptLimiter.ts`, `src/collections/LoginAttemptCollection.ts` | terminal approval concurrency, shared login budget and lockout (#3273), retry-safe database fixtures | [agents/terminal-auth-testing.md](agents/terminal-auth-testing.md) |\n| `src/services/DeviceCredentialService.ts` | per-person PIN layered on a device session (#3276), verifier seam for other credential kinds | this file, \"Security boundaries\" |\n| `src/services/PasswordCredentialService.ts`, `src/sveltekit/password-handlers.ts` | email + password sign-in and password lifecycle (#3274); shared scrypt in `credential-hash.ts` | this file, \"Security boundaries\"; README \"Password sign-in\" |\n| `src/retention.ts` | expired session/token/CLI-auth reaping and retention sweep wiring | [agents/retention.md](agents/retention.md) |\n\n## Models and authority\n\n- Users are global; tenant access comes through Membership (unique user/tenant).\n  User email is normalized and globally unique through readonly nullable\n  `emailKey`. `profileId` is a unique cross-package reference: at most one User\n  owns each non-null Profile.\n- Tenant uses STI and a materialized hierarchy, maximum depth 10.\n  `hierarchyPath`/`hierarchyLevel` are derived from `parentTenantId` by\n  `Tenant.save()` on every save (any caller-supplied value is recomputed) and\n  descendants are re-materialized when they change; never hand-maintain them.\n  Legacy rows are backfilled with `smrt db:materialize-tenant-hierarchy`\n  (`materializeTenantHierarchy()`). Tests that need a corrupt path must write it\n  with raw SQL (#3036).\n- Role with `tenantId = null` is available to all tenants; `isSystem` prevents\n  deletion. `inheritsToDescendants` is opt-in. Seed owner/admin/member/viewer\n  through `RoleCollection.seedSystemRoles()` at application initialization.\n- Group roles apply only in their own tenant. Use `getGroupIdsForTenant()`,\n  never cross-tenant `getGroupIds()`, for authorization.\n- Upward visibility is opt-in and read-only: `permissions.ancestorRead`\n  ({ roles, collections, maxDepth? }) lets a DESCENDANT membership contribute\n  declared `<collection>.read` at an ancestor, only when no membership resolved\n  there, intersected with BOTH the role's own catalog grants and the\n  principal's effective permissions in that descendant, and only for SYSTEM\n  roles (a tenant-scoped role sharing a declared slug is ignored). Off by default, never\n  write, never lateral, and never row visibility — sibling rows stay scoped by\n  tenancy/RLS. Read the permissions module before changing it.\n- Membership DENY always wins. Direct inactive membership blocks inherited\n  authority; a direct active membership pins resolution instead of unioning it\n  with ancestors. Read the permissions module before changing these rules.\n- AccessRequest has no generated API/MCP/CLI operations; access it through\n  `AccessRequestService`. Its JSON field is `requestContext`, not reserved\n  slug-scoping `context`.\n\n## Security boundaries\n\n- Generated REST/MCP operations on identity/RBAC models are list/get only.\n  Route authentication does not authorize authority mutations, and these models\n  are not tenant-scoped. Use permission-gated services or explicitly checked\n  consumer handlers. Generated CLI is list/get or closed (`cli: false` for\n  credential/grant models) because agents shell out to it; a `cli` without\n  `include` is full CRUD (#3742). Their catalog slugs stay full via\n  `USERS_AUTHORITY_CATALOG_MODELS`. Preserve the registry assertions in\n  `security-audit-1400.test.ts` and `issue-3742-cli-surface-lockdown.test.ts`.\n- Resource guards take the resource tenant, not the session tenant. Omit a\n  session membership when targeting a different tenant; mismatches fail closed.\n  `loadSessionContext().tenantAuthorization` must be checked by required-tenant\n  consumers: null membership can represent inherited authority.\n- Sessions use secure UUIDs; TTL is seconds (default seven days). Access marks\n  expired sessions EXPIRED. Magic-link tokens are single use.\n- `Session.authMethod` is server-set at mint time and never read from the\n  client; every mint site in this package sets it. A session with\n  `parentSessionId` is valid only while its parent validates\n  (`loadSessionContext` enforces this; there is no FK cascade by design), may\n  not switch to a tenant other than the parent's, and is revoked with its\n  parent by `destroySession`.\n- Credential sign-ins reserve through `LoginAttemptLimiter` BEFORE credential\n  work and key the subject on the submitted identifier, never a resolved user,\n  so unknown and wrong take the same path. Reservations are fail-closed: keep\n  them on failure, release on success or abort, never skip the reserve.\n  Limiter writes are raw SQL and bypass the change feed; the audit sink is the\n  observability seam, and it must never throw into the sign-in path.\n- `DeviceCredentialService` accepts a person credential only from a\n  first-class session whose `authMethod` is a device-enrollment method\n  (`terminal` by default) and that the host's `assertEnrolledDevice` confirms.\n  A layered or PIN session can never administer PINs regardless of\n  permissions. PIN hashes carry a per-row salt and the configured pepper;\n  treat an unset pepper as a production misconfiguration.\n- A person session carries the PERSON's authority (resolved from their own\n  membership on every load), never the device account's. `Session.data` keys\n  in `SESSION_DATA_KEYS` are server-set controls enforced by the model:\n  `permissionCeiling` only ever intersects (malformed fails closed to none)\n  and suppresses `superAdminBypass`/`systemContext`; `absoluteExpiresAt`\n  bounds `extend()` and `isValid()`; `idleSeconds` overrides the resolving\n  service's TTL policy. Never write them from client input. The ceiling is a\n  sign-in snapshot; `singleOccupant` revokes other children only AFTER a\n  successful mint. A `mustReset` sign-in mints with an empty ceiling and\n  `setPin` ends that session; do not grant it authority another way.\n- `UsersPasswordCredential` is one row per person, sensitive, with no\n  generated surface; `PasswordCredentialService` and its handlers are its only\n  read/write paths. Sign-in normalizes the email like `emailKey`, reserves\n  before work, always runs one scrypt verify (dummy hash when absent), never\n  creates a user, and maps every non-rate-limit refusal to one\n  `PasswordCredentialError`. It re-checks the credential after the mint (a\n  rehash that keeps row and version is confirmed by re-verifying); the\n  parameter-upgrade write is a guarded UPDATE that must never replace a\n  rotated password, and verification against a weaker stored hash is padded\n  to the policy's scrypt cost. Self-service writes are guarded on the proven\n  credential (first set insert-only); session sweeps run before and after\n  each write. Self-service needs the current password except for a first\n  set; `users.password.manage` follows the PIN's single-tenant target\n  rule and never resets the actor's own. Layered sessions never manage\n  passwords; a `mustChange` sign-in mints an empty ceiling.\n- 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": [
@@ -9977,7 +10854,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`, `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"
+      "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\n## OAuth credential retention\n\n`users-oauth-credentials` prunes expired authorization codes and access-token\nrevocations. Refresh grants (including consumed or revoked hashes) remain until\n30 days after their own expiry, so replay within their validity period and this\ngrace period still revokes the family. Later replay fails as an unknown token.\nThis bounds retained rotation history even for continuously active families.\nThe sweep locks each candidate family using the same row as token rotation,\nrechecks its descendants, and deletes the family only when none remain. Live\ngrants and revocations are never swept. Each family is a separate transaction;\nrolled-back contention retries follow the OAuth transaction policy. If the SQL\nadapter invalidates a connection (for example SQLite SQLITE_BUSY), the sweep\nreports failure; the host must acquire a fresh connection before retrying. It\nnever continues on an invalidated connection. Dry runs write nothing and\nreport approximate counts under concurrent writes. Clients and consent records\nremain for application-managed lifecycle/audit. Opt-out and unregister work as\nfor the other retention tasks. No raw bearer or credential hash is logged.\n"
     }
   ],
   "recipes": [