najm-auth 6.2.0 → 6.3.0

package/README.md

@@ -635,6 +635,29 @@ An upgrade alone does not rewrite unsafe queries in consumers. Keep role
 and cross-user integration tests in each app. `@Policy` and `@CanRead` check
 permissions, not the ownership of a requested record ID.
 
+### Row conditions and owned-id subqueries (6.3+)
+
+A rule may also hold `when()` conditions on the owned row. After a join chain
+they narrow it; on their own they are the whole rule, for rows that belong to
+an audience rather than to one linked person. A function receives the user id
+and the rule's role. `ownedIds(token, role, userId)` is the subquery of ids a
+user owns through another token, for use inside a condition.
+
+```typescript
+import { own, join, where, when, ownedIds } from 'najm-auth';
+
+export const Alert = own(alerts, { adminRoles: ['admin'] })
+  // Alerts about my children that are addressed to parents
+  .for('parent', join(alerts.studentId, students.id), where(students.parentUserId),
+    when(eq(alerts.audience, 'parents')))
+  // Alerts naming nobody, for classes I teach
+  .for('teacher', when(isNull(alerts.studentId),
+    (userId, role) => inArray(alerts.classId, ownedIds(Class, role, userId))));
+```
+
+`own(table, { name })` sets the token's resource name when it should differ
+from the table's.
+
 ### Advanced Ownership: Multi-Role Scoping
 
 ```typescript

package/dist/index.d.ts

@@ -2709,6 +2709,12 @@ interface OwnerStep {
     col: any;
 }
 type OwnershipStep = JoinStep | OwnerStep;
+/** A condition on the owned row; a function receives the user id and the rule's role. */
+type RowRule = SQL | ((userId: string, role: string) => SQL);
+interface WhenStep {
+    type: 'when';
+    rules: RowRule[];
+}
 /**
  * JOIN step — links two columns across tables.
  * The target table is inferred from the right column.
@@ -2722,6 +2728,21 @@ declare function join(left: any, right: any): JoinStep;
  * @example where(teachers.userId)
  */
 declare function where(col: any): OwnerStep;
+/**
+ * Row-condition step — a condition on the owned row itself.
+ *
+ * After a join chain it narrows the rows the chain reaches ("…and the alert is
+ * for parents"). On its own it is the whole rule, for rows that belong to an
+ * audience rather than to one linked person ("every published notice for
+ * parents"). Several rules in one step, and several steps, are AND-ed.
+ *
+ * @example
+ * own(alerts)
+ *   .for('parent', join(alerts.studentId, students.id), where(students.parentUserId),
+ *     when(eq(alerts.audience, 'parents')))
+ *   .for('teacher', when(isNull(alerts.studentId), (userId) => eq(alerts.createdBy, userId)))
+ */
+declare function when(...rules: RowRule[]): WhenStep;
 type ScopeResult = {
     query: any;
     condition: any;
@@ -2729,6 +2750,8 @@ type ScopeResult = {
 interface OwnershipTokenOptions {
     /** Admin roles that bypass all scoping. Falls back to global admin roles if not set. */
     adminRoles?: string[];
+    /** Resource name (default: the table's name), e.g. for permission and policy names. */
+    name?: string;
 }
 declare class OwnershipToken {
     readonly symbol: symbol;
@@ -2739,8 +2762,12 @@ declare class OwnershipToken {
     private _adminRoles?;
     constructor(table: any, opts?: OwnershipTokenOptions);
     private isAdmin;
-    /** Define scope rules for a role. */
-    for(role: string, ...steps: OwnershipStep[]): this;
+    /**
+     * Define the scope rule for a role: a join chain ending in `where()`, and/or
+     * `when()` row conditions. A chain with conditions reaches the rows the
+     * chain reaches that also satisfy them; conditions alone are the whole rule.
+     */
+    for(role: string, ...steps: Array<OwnershipStep | WhenStep>): this;
     /**
      * Column to verify ownership before write operations (create/update).
      * @example .writeBy(grades.studentId)
@@ -2758,6 +2785,17 @@ declare class OwnershipToken {
      */
     applyScopeSplit(uid: string, role: string, query: any): ScopeResult;
 }
+/**
+ * The ids of `token`'s rows that a `role` user owns, as a subquery — for a
+ * `when()` condition on another resource: "one of the classes this parent's
+ * children are in". A role that bypasses scoping gets every id; a role with no
+ * rule gets none.
+ *
+ * @example
+ * own(announcements).for('parent', when((userId, role) =>
+ *   inArray(announcements.classId, ownedIds(Class, role, userId))))
+ */
+declare function ownedIds(token: OwnershipToken, role: string, userId: string): any;
 /**
  * Start an ownership definition chain.
  *
@@ -2770,6 +2808,9 @@ declare class OwnershipToken {
  * // With explicit admin roles (avoids global state):
  * export const Grade = own(grades, { adminRoles: ['admin', 'principal'] })
  *   .for('teacher', join(grades.studentId, students.id), where(teachers.userId));
+ *
+ * // With a resource name other than the table's:
+ * export const Report = own(reportRows, { name: 'reports' });
  */
 declare function own(table: any, opts?: OwnershipTokenOptions): OwnershipToken;
 
@@ -3237,4 +3278,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AdministrativeDelivery, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, type ConsumedSetPasswordToken, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GitHubOAuthConfig, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnedWhere, type OwnershipConditionMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipReadContext, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RefreshedSession, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, SessionInvalidationService, type SetPasswordToken, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TemporaryCredentialReset, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authEmailRateLimitKey, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, ownershipCondition, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AdministrativeDelivery, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, type ConsumedSetPasswordToken, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GitHubOAuthConfig, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnedWhere, type OwnershipConditionMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipReadContext, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RefreshedSession, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RowRule, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, SessionInvalidationService, type SetPasswordToken, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TemporaryCredentialReset, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, type WhenStep, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authEmailRateLimitKey, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, ownedIds, ownershipCondition, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, when, where };

package/dist/index.js

@@ -6193,7 +6193,9 @@ var revokeTokenDto = z4.object({
 });
 
 // src/ownership/scopedOwnership.ts
-import { aliasedTable, eq as eq8, getTableColumns, sql as sql5 } from "drizzle-orm";
+import { aliasedTable, and as and6, eq as eq8, getTableColumns, is, sql as sql5 } from "drizzle-orm";
+import { PgTable, QueryBuilder as PgQueryBuilder } from "drizzle-orm/pg-core";
+import { SQLiteTable, QueryBuilder as SQLiteQueryBuilder } from "drizzle-orm/sqlite-core";
 var DEFAULT_ADMIN_ROLES = ["admin"];
 var DRIZZLE_NAME = Symbol.for("drizzle:Name");
 var DRIZZLE_BASE_NAME = Symbol.for("drizzle:BaseName");
@@ -6209,6 +6211,11 @@ function where(col) {
   return { type: "owner", col };
 }
 __name(where, "where");
+function when(...rules) {
+  return { type: "when", rules };
+}
+__name(when, "when");
+var resolveWhen = /* @__PURE__ */ __name((step, uid, role) => and6(...step.rules.map((rule) => typeof rule === "function" ? rule(uid, role) : rule)), "resolveWhen");
 function isAliased(table) {
   return table?.[DRIZZLE_IS_ALIAS] === true;
 }
@@ -6296,7 +6303,7 @@ var OwnershipToken = class {
   _writeScopeCol;
   _adminRoles;
   constructor(table, opts) {
-    const name = table[DRIZZLE_NAME] ?? table?._.baseName ?? table?._.name ?? "resource";
+    const name = opts?.name ?? table[DRIZZLE_NAME] ?? table?._.baseName ?? table?._.name ?? "resource";
     this.name = name;
     this.table = table;
     this.symbol = Symbol(name);
@@ -6305,9 +6312,26 @@ var OwnershipToken = class {
   isAdmin(role) {
     return (this._adminRoles ?? DEFAULT_ADMIN_ROLES).includes(role);
   }
-  /** Define scope rules for a role. */
+  /**
+   * Define the scope rule for a role: a join chain ending in `where()`, and/or
+   * `when()` row conditions. A chain with conditions reaches the rows the
+   * chain reaches that also satisfy them; conditions alone are the whole rule.
+   */
   for(role, ...steps) {
-    this._rules[role] = compile(steps);
+    const chain = steps.filter((step) => step.type !== "when");
+    const conditions = steps.filter((step) => step.type === "when");
+    if (!conditions.length) {
+      this._rules[role] = compile(chain);
+      return this;
+    }
+    const joined = chain.length ? compile(chain) : void 0;
+    this._rules[role] = (uid, query) => {
+      const narrowing = and6(...conditions.map((condition) => resolveWhen(condition, uid, role)));
+      if (!joined)
+        return { query, condition: narrowing };
+      const scoped = joined(uid, query);
+      return { query: scoped.query, condition: and6(scoped.condition, narrowing) };
+    };
     return this;
   }
   /**
@@ -6349,6 +6373,18 @@ var OwnershipToken = class {
     return rule(uid, query);
   }
 };
+function ownedIds(token, role, userId) {
+  const table = token.table;
+  if (!table?.id)
+    throw new Error(`ownedIds(): ${token.name} has no id column.`);
+  const builder = is(table, SQLiteTable) ? new SQLiteQueryBuilder() : is(table, PgTable) ? new PgQueryBuilder() : null;
+  if (!builder)
+    throw new Error(`ownedIds(): ${token.name} is not a pg or sqlite table.`);
+  const rows = builder.select({ id: table.id }).from(table);
+  const { query, condition } = token.applyScopeSplit(userId, role, rows);
+  return condition === null ? query : query.where(condition);
+}
+__name(ownedIds, "ownedIds");
 function own(table, opts) {
   return new OwnershipToken(table, opts);
 }
@@ -6704,7 +6740,7 @@ __name(Policy, "Policy");
 
 // src/ownership/OwnedDecorator.ts
 import "reflect-metadata";
-import { sql as sql7, and as and6 } from "drizzle-orm";
+import { sql as sql7, and as and7 } from "drizzle-orm";
 import { Injectable as Injectable17, Inject as Inject19, DI as DI3, Container as Container2, REQUEST_ID } from "najm-core";
 import { USER as USER2 } from "najm-guard";
 
@@ -6866,7 +6902,7 @@ function Owned(token, ...alternatives) {
         return null;
       if (filtered.length === 1)
         return filtered[0];
-      return and6(...filtered);
+      return and7(...filtered);
     }
     __name(combineConditions, "combineConditions");
     function applyQueryOptions(query, opts = {}, whereCondition) {
@@ -7386,7 +7422,7 @@ import { Inject as Inject24, Injectable as Injectable21 } from "najm-core";
 import { Transaction as Transaction5 } from "najm-database";
 
 // src/oauth/OAuthAccountRepository.ts
-import { and as and7, eq as eq9 } from "drizzle-orm";
+import { and as and8, eq as eq9 } from "drizzle-orm";
 import { Inject as Inject23, Repository as Repository7 } from "najm-core";
 import { DB as DB7 } from "najm-database";
 var __decorate37 = function(decorators, target, key, desc) {
@@ -7411,11 +7447,11 @@ var OAuthAccountRepository = class OAuthAccountRepository2 {
     return this.schema.oauthAccounts;
   }
   async getByProviderAccount(provider, providerAccountId) {
-    const [account] = await this.db.select().from(this.accounts).where(and7(eq9(this.accounts.provider, provider), eq9(this.accounts.providerAccountId, providerAccountId))).limit(1);
+    const [account] = await this.db.select().from(this.accounts).where(and8(eq9(this.accounts.provider, provider), eq9(this.accounts.providerAccountId, providerAccountId))).limit(1);
     return account;
   }
   async getByUserProvider(userId, provider) {
-    const [account] = await this.db.select().from(this.accounts).where(and7(eq9(this.accounts.userId, userId), eq9(this.accounts.provider, provider))).limit(1);
+    const [account] = await this.db.select().from(this.accounts).where(and8(eq9(this.accounts.userId, userId), eq9(this.accounts.provider, provider))).limit(1);
     return account;
   }
   async create(data) {
@@ -8548,6 +8584,7 @@ export {
   normalizeTunisianPhone,
   oauthAccountsTable,
   own,
+  ownedIds,
   ownershipCondition,
   parseSchema,
   permissionIdParam,
@@ -8580,5 +8617,6 @@ export {
   userStatusEnum,
   usersTable,
   verifyTokenDto,
+  when,
   where
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [
@@ -97,8 +97,8 @@
     "najm-database": "^2.2.1",
     "najm-guard": "^2.2.1",
     "najm-i18n": "^2.1.3",
-    "najm-cache": "^2.2.0",
-    "najm-email": "^3.0.0",
+    "najm-cache": "^2.3.0",
+    "najm-email": "^3.1.0",
     "najm-rate": "^3.0.0",
     "najm-validation": "^2.0.3",
     "jsonwebtoken": "^9.0.3",