
# メソッドセキュリティ

Bean のメソッドに付けたアノテーションが、誰がそれを呼べるかを示します。チェックは、呼び出し元がコントローラーでも、スケジュールされたジョブでも、Flutter のウィジェットでも、すべての呼び出しの前 (または後) に実行されます。許可されない呼び出しは `AccessDeniedException` で失敗し、メソッドは実行されません。

## 使う理由

手でチェックするアクセスルール (`if (!user.isAdmin) throw ...`) はコード中に散らばり、一つのチェックを忘れるとメソッドが開放されてしまいます。アノテーションはルールを、それが保護するメソッドの上、読み手の目に入る場所に置き、メソッドへのすべての経路でチェックが実行されます。ルールは URL ではなくサービスにあるため、ジョブや別のサービスから呼ばれた場合もメソッドを保護します。

## 例

```dart
@Service()
class OrderService {
  OrderService(this.orders);

  final OrderRepository orders;

  // 管理者はどの注文もキャンセルでき、他のユーザーは自分のものだけ。
  @PreAuthorize("hasRole('ADMIN') or #order.owner == principal.username")
  Future<void> cancel(Order order) => orders.delete(order);

  // 呼び出し元が注文を見られるかは、読み込まれたものによって決まる。
  @PostAuthorize('returnObject.owner == authentication.name')
  Future<Order> find(int id) async => (await orders.findById(id))!;

  // 権限の単純なリストがルールのすべて。
  @Secured(['ROLE_SUPPORT'])
  Future<void> refund(int id) async {}

  // 引数から呼び出し元自身の注文だけを残す。
  @PreFilter('filterObject.owner == authentication.name')
  Future<void> archive(List<Order> orders) async {}

  // 各ユーザーはリストから自分の注文だけを受け取る。
  @PostFilter('filterObject.owner == authentication.name')
  Future<List<Order>> all() => orders.findAll();
}
```

## アノテーション

| アノテーション | 働き |
|---|---|
| `@PreAuthorize(expression)` | 式が `true` のときだけメソッドを実行する。 |
| `@PostAuthorize(expression)` | 式が `true` のときだけ結果 (`returnObject`) を呼び出し元に渡す。メソッドはすでに実行されている。変更ではなく読み取りに使う。 |
| `@Secured([...])` | ユーザーが列挙された権限 (完全な名前、`ROLE_ADMIN`) のいずれかを持つときだけメソッドを実行する。 |
| `@PreFilter(expression, filterTarget:)` | コレクションの引数から、式が `false` になる要素 (`filterObject`) を取り除く。コレクションのパラメーターが複数ある場合は、`filterTarget` で一つを指定する。 |
| `@PostFilter(expression)` | 返された `List`、`Set`、`Map` から、式が `false` になる要素を取り除く。それ以外の結果の型は呼び出しを失敗させる。 |

クラスに付けたアノテーションは、独自のアノテーションを持たないすべてのメソッドに適用されます (ゲッターとセッターを除く)。`PreAuthorize` を継承する `const` クラスは、固定の合成アノテーションとして動きます。

```dart
class AdminOnly extends PreAuthorize {
  const AdminOnly() : super("hasRole('ADMIN')");
}
```

## 呼び出しの結果

| 状況 | 結果 |
|---|---|
| セキュリティコンテキストに認証がまったくない | 式を実行する前に `AuthenticationCredentialsNotFoundException` |
| 式が否と言う | `AccessDeniedException` |
| 式が失敗するか、`bool` を返さない | `ArgumentError`。メソッドは実行されない |

同期メソッドは例外を投げます。`async` メソッドは失敗した `Future` を返し、`@PreAuthorize` ではその本体は決して実行されません。このパッケージは HTTP について何も知りません。Web アプリケーションでは、`spring_boot_starter_security` がこれらの例外を `401` と `403` の応答に変換します。

## 式

式は Spring と同じく SpEL です。

| 式の中 | 意味 |
|---|---|
| `hasRole('ADMIN')`、`hasAnyRole('A', 'B')` | ユーザーが `ROLE_ADMIN` / いずれかのロールを持つ。`RoleHierarchy` Bean が適用される。 |
| `hasAuthority('SCOPE_read')`、`hasAnyAuthority(...)` | ユーザーが、完全な名前で書いた権限を持つ。 |
| `isAuthenticated()`、`isFullyAuthenticated()`、`isAnonymous()` | ユーザーのログインのしかた。 |
| `permitAll`、`denyAll` | 常に許可 / 決して許可しない。 |
| `principal`、`authentication` | ユーザー (`principal.username`)、`Authentication` (`authentication.name`)。 |
| `#order`、`#p0`、`#a0` | 名前と位置による引数。 |
| `returnObject` | 結果 (`@PostAuthorize`)。 |
| `filterObject` | 要素 (`@PreFilter`、`@PostFilter`)。 |
| `hasPermission(#order, 'cancel')`、`hasPermission(#id, 'Order', 'cancel')` | `PermissionEvaluator` Bean に問い合わせる。なければ拒否する。 |
| `@shop.isOpen()` | Bean。そのクラスは `@Introspected` でなければならない。 |

- メソッドが使う、Bean 自身のパッケージのクラス (上の `Order`) は、`@Introspected` なしで式から読めます。
- `User` のパスワードと `Authentication` のクレデンシャルは決して読めません。
- `hasRole` はプレフィックス `ROLE_` を付けます。プレフィックスなしで名付けられた権限 (ディレクトリからの単なる `ADMIN`) には、`GrantedAuthorityDefaults('')` Bean を宣言してください。

```dart
@Bean()
GrantedAuthorityDefaults authorityDefaults() => const GrantedAuthorityDefaults('');
```

## ロール階層

`RoleHierarchy` Bean は、式 (`hasRole`、`hasAuthority`、およびその `Any` 形) の中で、あるロールに他のロールを含めます。

```dart
@Bean()
RoleHierarchy roleHierarchy() => RoleHierarchyImpl.fromHierarchy('''
  ROLE_ADMIN > ROLE_STAFF
  ROLE_STAFF > ROLE_USER
''');
```

一行に一つ、`A > B` または `A > B > C` のルールを、完全な権限名で書きます。ルールは連鎖します。管理者はユーザーでもあります。ルールでない行や循環は `ArgumentError` です。

## パーミッションエバリュエーター

オブジェクトに依存するルール (`このユーザーはこの文書を編集できるか?`) には、`PermissionEvaluator` を実装して Bean として宣言します。

```dart
@Component()
class OrderPermissions implements PermissionEvaluator {
  @override
  bool hasPermission(Authentication authentication, Object? target, Object permission) =>
      target is Order && permission == 'cancel' && target.owner == authentication.name;

  @override
  bool hasPermissionById(Authentication authentication, Object? targetId, String targetType, Object permission) =>
      false; // ID でオブジェクトを読み込んで判断する
}
```

そうした Bean がなければ、`hasPermission` は常に拒否します。

## チェックの実行方法

- **Bean のプロキシを通して**、Spring と同じく実行されます。Bean の内部からの呼び出し (`this.cancel(...)`) はチェックされません。プロキシはジェネレーターが書き出すため、アプリケーションには `spring_core_dart_generator` が必要です。
- **常に有効です。** Spring は `@EnableMethodSecurity` を必要としますが、ここでは依存関係だけで十分です。そうしたアノテーションを持ちながらプロキシ化できない Bean (例えば `final` クラス) は、チェックなしで動く代わりに起動を失敗させます。
- **起動時に解析されます。** 式のタイプミスはアプリケーションを止めます。
- **他のすべてのアドバイスより前に実行されます。** `@Cacheable`、`@Validated`、アプリケーションのアスペクトは、認可された呼び出しでだけ実行されます。そのため、キャッシュされた結果が、メソッドを呼べない呼び出し元に返されることはありません。

## Spring (Java) との対応

```java
@EnableMethodSecurity(securedEnabled = true)
@Configuration
class MethodSecurityConfig {}

@PreAuthorize("hasRole('ADMIN') or #order.owner == principal.username")
public void cancel(Order order) { ... }
```

アノテーションと式は Spring のものです。まだないもの: JSR-250 (`@RolesAllowed`)、パラメーター付きのアノテーションテンプレート、`@AuthorizeReturnObject`、`@HandleAuthorizationDenied`、認可イベント、ACL テーブル。

## 関連項目

- [セキュリティコンテキスト](security-context.md)
- [SpEL](../spring-core-dart/spel/index.md)
- [AOP プロキシ](../spring-core-dart/aop/proxies.md)
