
# spring_security_core

`spring_security_core` is the part of security that does not depend on HTTP: who is logged in, users and their password hashes, the login check, and access rules on bean methods (`@PreAuthorize`, `@PostAuthorize`, `@Secured`, `@PreFilter` and `@PostFilter`). It is the Dart port of Spring Security's core and method security.

## Why

An application must know its user and check what that user may do, wherever the call comes from: a web request, a scheduled job, a button in a Flutter app. With this package the rules sit on the methods they protect, one line each, instead of `if` checks spread over the code. Passwords are stored as slow, salted hashes in Spring Security's formats, so a Dart and a Java service can share a user table.

- **On a server**, list [spring_boot_starter_security](../spring-boot-starter-security/index.md) instead: it brings this package and adds the filter chain that logs in the user of each request.
- **In a Flutter app**, or a program without HTTP, this package alone is enough.

## Setup

```yaml
# pubspec.yaml
dependencies:
  spring_security_core: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # writes the proxies method security needs
```

It brings and re-exports `spring_boot_dart` and the logging starter, so the application lists it (or the security starter) alone. One import is enough: `package:spring_security_core/spring_security_core.dart`.

## Example

```dart
import 'package:spring_security_core/spring_security_core.dart';

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

  final OrderRepository orders;

  // Admins cancel any order, other users only their own.
  @PreAuthorize("hasRole('ADMIN') or #order.owner == principal.username")
  Future<void> cancel(Order order) => orders.delete(order);

  // Each user gets only their own orders out of the list.
  @PostFilter('filterObject.owner == authentication.name')
  Future<List<Order>> all() => orders.findAll();
}

@Configuration()
class Users {
  // The users and their hashed passwords.
  @Bean()
  UserDetailsService users() => InMemoryUserDetailsManager([
        User.withUsername('ada').password('{argon2}\$argon2id\$v=19\$...').roles(['ADMIN']).build(),
        User.withUsername('bob').password('{argon2}\$argon2id\$v=19\$...').roles(['USER']).build(),
      ]);
}
```

```dart
// A Flutter app logs the user in and keeps the result.
final result = await authenticationManager.authenticate(
  UsernamePasswordAuthenticationToken.unauthenticated(name, password),
);
SecurityContextHolder.setContext(SecurityContextImpl(result));

await orderService.cancel(order); // checked against the logged-in user
```

## What starts

- **Method security is always on.** There is no `@EnableMethodSecurity`: the dependency is enough, so an annotation is never silently ignored. A bean with such annotations that cannot be proxied fails the startup instead of running unchecked.
- **Expressions are parsed at startup.** A typo stops the application instead of opening the method.
- **An `AuthenticationManager`** is built from your `UserDetailsService` bean (a `DaoAuthenticationProvider` with the `PasswordEncoder` bean, or the delegating encoder), or from your `AuthenticationProvider` beans.
- **Password checks are bounded:** at most half the processors hash at once, on another isolate on the Dart VM.

## What is inside

- [Method security](method-security.md): `@PreAuthorize`, `@PostAuthorize`, `@Secured`, `@PreFilter`, `@PostFilter`, expressions, role hierarchies.
- [The security context](security-context.md): `SecurityContextHolder`, zones, running as a user, listening to logins.
- [Authentication](authentication.md): users, `UserDetailsService`, `AuthenticationManager`, events.
- [Password encoders](password-encoders.md): Argon2, PBKDF2, scrypt, the delegating encoder and hash upgrades.
- [LoginSession and the shared interfaces](login-session.md): the login of a client application whatever the provider, `SecretStore`, `AuthorizationWindow`, `OAuth2Token`.
- [Testing](testing.md): `withMockUser`, `withAuthentication`, `withAnonymousUser`.
- [All properties](properties.md): the two password check limits.
- [Differences from Spring](differences.md): what works differently than in Spring Security.

## In Spring (Java)

```java
@EnableMethodSecurity
@Configuration
class SecurityConfig {}

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

Differences that matter:

- No `@EnableMethodSecurity`: method security is always on.
- The security context is kept per `Zone`, not per thread.
- BCrypt is not available; new hashes are `{argon2}`, which Spring checks too.
- The full list is on [Differences from Spring](differences.md).

## See also

- [spring_boot_starter_security](../spring-boot-starter-security/index.md)
- [spring_boot_starter_supabase](../spring-boot-starter-supabase/index.md)
- [SpEL](../spring-core-dart/spel/index.md)
- [AOP proxies](../spring-core-dart/aop/proxies.md)
