Autenticação com token e favoritos sincronizados

No fim desta aula consegues

• Distinguir autenticação de autorização, e sessões por cookie de tokens Bearer.
• Ler um JWT e explicar cabeçalho, payload, assinatura e expiração.
• Descrever o fluxo authorization code com PKCE e o papel do refresh token.
• Obter, guardar e usar o token da API do curso com renovação automática em 401.
• Sincronizar favoritos com o backend com UI otimista e rollback em caso de erro.

Autenticação vs autorização; cookies vs tokens

• Autenticação: quem és (login, biometria, chave). Autorização: o que podes fazer (ler os favoritos do teu grupo, não os dos outros).
• 401 Unauthorized = não sei quem és: token em falta ou expirado. 403 Forbidden = sei quem és, mas não podes.
• Na web: sessão guardada no servidor e um cookie que o browser envia sozinho em cada pedido. O risco típico é CSRF.
• Em mobile: não há browser a gerir cookies. A app guarda um token e envia-o explicitamente em Authorization: Bearer ….
• Um token assinado é stateless: o servidor valida a assinatura sem ir à base de dados. Escala melhor; revogar é mais difícil.

Para os testes: 401 é autenticação, 403 é autorização; em mobile usam-se tokens Bearer, não cookies.

JWT (1 de 2): o que tem dentro

• Três partes em base64url separadas por pontos: header.payload.signature.
• Header: {"alg":"HS256","typ":"JWT"}. Payload: as claims: sub (quem), iss (quem emitiu), iat e exp (quando), e claims próprias como grupo ou scope.
• Signature: HMAC (chave partilhada) ou RSA/ECDSA (par de chaves) sobre o header e o payload.

{
  "sub": "grupo-07",
  "iss": "api.pdm.example",
  "iat": 1761494400,
  "exp": 1761495300,
  "scope": "forecast warnings favorites"
}

• Base64 não é cifra: qualquer pessoa lê o payload. A app pode ler exp para saber que vai expirar sem fazer um pedido.

Para os testes: JWT = header.payload.signature; o payload é legível por todos, não é secreto.

JWT (2 de 2): assinatura, expiração e o que nunca lá vai

• A assinatura garante integridade: se alguém mudar "sub": "grupo-07" para "grupo-01", a assinatura deixa de bater e o servidor rejeita.
• Só o servidor valida. Com HS256 o cliente não tem a chave; com RS256 poderia validar com a chave pública, mas não precisa.
• exp curto (15 min a 1 h): um token roubado vale pouco tempo. Sem exp é um token eterno, e isso é um bug de segurança.
• Nunca no JWT: passwords, dados pessoais sensíveis, segredos. Vai em claro, em cada pedido, e acaba em logs.
• Ataques reais do passado: "alg":"none" aceite pelo servidor, e chaves HS256 fracas quebradas por força bruta. Bibliotecas atuais rejeitam ambos.

Para os testes: a assinatura dá integridade, não confidencialidade; nunca se põem dados sensíveis num JWT.

OAuth2 e OIDC em traços largos: authorization code + PKCE

• O problema: a app quer aceder ao calendário Google do utilizador sem alguma vez conhecer a password do Google.
• OAuth2 é autorização delegada: a app abre o browser do sistema, o utilizador entra no Google, o Google devolve um code por deep link, e a app troca o code por tokens.
• PKCE: a app gera um code_verifier aleatório e envia o seu hash (code_challenge). Só quem tem o verifier troca o code. Obrigatório em apps móveis, porque não têm onde guardar um client secret.
• OIDC = OAuth2 + identidade: devolve também um id_token (JWT) que diz quem é o utilizador. É o "Entrar com Google".
• Em Flutter: flutter_appauth ou o SDK de cada fornecedor. Sempre Custom Tabs / ASWebAuthenticationSession, nunca um webview próprio (o utilizador não deve escrever a password dentro da tua app).

Para os testes: apps móveis não guardam passwords nem client secrets; usam authorization code com PKCE no browser do sistema.

Access token curto, refresh token longo, logout

• Renovação: em 401, pede um access novo com o refresh e repete o pedido original uma vez. Se o refresh também falhar, logout.
• Logout: apagar os dois do dispositivo, revogar o refresh no servidor, limpar a cache com dados do utilizador. Na API do curso há um só token (de grupo), mas o padrão é o mesmo.

Para os testes: access curto em cada pedido; refresh longo em secure storage, só para renovar; logout apaga ambos.

Biometria e Sign in with Apple

• local_auth: Face ID, Touch ID, impressão digital. Devolve só "sim" ou "não" à app. Nunca fala com o servidor.
• Uso certo: desbloqueio local. A app do banco já tem sessão (refresh token guardado); a biometria decide se a app o pode usar agora.
• Uso errado: "autenticar no servidor com a biometria". O servidor nunca vê a biometria; se o refresh token não existir, a biometria não cria sessão nenhuma.
• Sign in with Apple é obrigatório na App Store se a app oferece outro login social (Google, Facebook). Inclui email de relay para quem não quer dar o seu.
• Passkeys (WebAuthn): a próxima etapa. Sem passwords, chave privada no dispositivo, desbloqueada por biometria. Já suportadas no Android e no iOS.

Para os testes: a biometria desbloqueia localmente; a autenticação no servidor continua a ser feita pelo token.

Repositório da aula

git clone https://github.com/pdm-daw-2026/pdm-aula-17.git
cd pdm-aula-17/starter
flutter pub get
flutter run --dart-define-from-file=.env.json

• starter/ é a app da aula 16 (cache e TokenStorage) com TODOs de 1 a 5 e testes a falhar. Cria o .env.json com o PDM_CLIENT_ID e o PDM_SECRET do teu grupo; já está no .gitignore.
• solucao/ é o estado final: token renovado sozinho, favoritos iguais em dois telemóveis, logout que limpa tudo.
• O ApiClient do starter já tem delete, além de get e post.

1. Obter o token e guardá-lo em segurança

class AuthService {
  AuthService(this._api, this._storage);
  final ApiClient _api;
  final TokenStorage _storage;   // flutter_secure_storage, da aula 16

  static const _clientId = String.fromEnvironment('PDM_CLIENT_ID');
  static const _secret = String.fromEnvironment('PDM_SECRET');

  Future<String> obterToken() async {
    final json = await _api.post('/v1/auth/token', body: {
      'client_id': _clientId,
      'secret': _secret,
    });
    final token = json['access_token'] as String;
    await _storage.guardar(token);
    return token;
  }

  Future<String> tokenAtual() async =>
      await _storage.ler() ?? await obterToken();
}

1. Token: o que interessa

• tokenAtual() devolve o que está guardado ou pede um novo. Nunca há dois caminhos para obter token: só este.
• O token vai para o TokenStorage (Keychain/Keystore), nunca para shared_preferences nem para a base de dados. Foi a matéria da aula 16.
• String.fromEnvironment é resolvido em compilação: o valor fica no binário. Para a API do curso é aceitável (token de grupo, revogável); em produção o login é do utilizador.
• Um token guardado pode já estar expirado quando a app arranca. Não faz mal: o interceptor do passo 2 trata do 401.
• Opcional: ler o exp do payload (base64url do segundo segmento) e renovar antes de expirar. Poupa um 401 por sessão.

2. AuthClient: Bearer em todos os pedidos, renovação em 401

class AuthClient extends http.BaseClient {
  AuthClient(this._inner, this._auth);
  final http.Client _inner;
  final AuthService _auth;

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) async {
    if (request.url.path.endsWith('/auth/token')) return _inner.send(request);
    var resposta = await _enviarCom(await _auth.tokenAtual(), request);
    if (resposta.statusCode == 401) {
      resposta = await _enviarCom(await _auth.obterToken(), request);  // renova uma vez
    }
    return resposta;
  }

  Future<http.StreamedResponse> _enviarCom(String token, http.BaseRequest original) {
    final pedido = http.Request(original.method, original.url)
      ..headers.addAll(original.headers)
      ..headers['Authorization'] = 'Bearer $token';
    if (original is http.Request) pedido.bodyBytes = original.bodyBytes;
    return _inner.send(pedido);
  }
}

// main.dart: o ApiClient passa a usar o AuthClient por baixo
final api = ApiClient(baseUrl: baseUrl, client: AuthClient(http.Client(), auth));

2. Interceptor: o que interessa

• BaseClient.send é o ponto por onde passam todos os pedidos do http. É o interceptor da aula 12, agora com código.
• O pedido de token não leva token. Sem a primeira linha do send, tokenAtual() chamava obterToken(), que passava pelo send, que chamava tokenAtual(): recursão infinita.
• Um BaseRequest só pode ser enviado uma vez. Por isso _enviarCom cria um pedido novo com os mesmos método, URL, headers e corpo.
• Renova uma vez. Se o segundo pedido também dá 401, o problema não é o token expirado: é o segredo errado ou o grupo revogado, e a app tem de mostrar isso.
• Com dio é um QueuedInterceptor com onError: a fila evita que dez pedidos em paralelo com 401 peçam dez tokens novos. Aqui, o AuthService devia guardar o Future em curso para o mesmo efeito.

3. FavoritosRepository sobre /v1/me/favorites

abstract class FavoritosRepository {
  Future<List<int>> listar();
  Future<void> adicionar(int localidadeId);
  Future<void> remover(int localidadeId);
}

class FavoritosRepositoryApi implements FavoritosRepository {
  FavoritosRepositoryApi(this._api);
  final ApiClient _api;

  @override
  Future<List<int>> listar() async {
    final json = await _api.get('/v1/me/favorites') as List<dynamic>;
    return json.map((e) => (e as Map<String, dynamic>)['locationId'] as int).toList();
  }

  @override
  Future<void> adicionar(int localidadeId) =>
      _api.post('/v1/me/favorites', body: {'locationId': localidadeId});

  @override
  Future<void> remover(int localidadeId) =>
      _api.delete('/v1/me/favorites/$localidadeId');
}

3. FavoritosNotifier: UI otimista com rollback

class FavoritosNotifier extends ChangeNotifier {
  FavoritosNotifier(this._repo);
  final FavoritosRepository _repo;
  Set<int> _ids = {};
  bool contem(int id) => _ids.contains(id);

  Future<void> carregar() async {
    _ids = (await _repo.listar()).toSet();
    notifyListeners();
  }

  /// Devolve false se o servidor recusou e a alteração foi desfeita.
  Future<bool> alternar(int id) async {
    final antes = {..._ids};
    final adicionar = !_ids.contains(id);
    adicionar ? _ids.add(id) : _ids.remove(id);        // 1. a UI muda já
    notifyListeners();
    try {
      await (adicionar ? _repo.adicionar(id) : _repo.remover(id));   // 2. servidor
      return true;
    } catch (_) {
      _ids = antes;                                     // 3. rollback
      notifyListeners();
      return false;
    }
  }
}

3. O botão de favorito com feedback em caso de erro

class BotaoFavorito extends StatelessWidget {
  const BotaoFavorito({super.key, required this.localidadeId});
  final int localidadeId;

  @override
  Widget build(BuildContext context) {
    final marcado = context.select<FavoritosNotifier, bool>((f) => f.contem(localidadeId));
    return IconButton(
      icon: Icon(marcado ? Icons.star : Icons.star_border),
      tooltip: marcado ? 'Remover dos favoritos' : 'Adicionar aos favoritos',
      onPressed: () async {
        final ok = await context.read<FavoritosNotifier>().alternar(localidadeId);
        if (!ok && context.mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Não foi possível guardar o favorito. Tenta de novo.')),
          );
        }
      },
    );
  }
}

3. Favoritos sincronizados: o que interessa

• UI otimista: a estrela acende no instante do toque, antes da resposta do servidor. O utilizador não espera 800 ms por um ícone.
• Rollback: guarda-se o estado anterior (antes); se o servidor recusa, repõe-se e avisa-se. Nunca fica uma estrela acesa que o servidor não conhece.
• alternar devolve bool em vez de guardar a mensagem no notifier: o widget que disparou a ação é quem mostra o SnackBar, com context.mounted depois do await.
• context.select reconstrói o botão só quando este favorito muda, não quando qualquer um muda.
• O POST não é repetido pelo ApiClient (aula 14); se falhar, o rollback é a resposta certa. Um DELETE repetido não faz mal: é idempotente.

4. Ecrã inicial com favoritos iguais em dois telemóveis

class FavoritosScreen extends StatelessWidget {
  const FavoritosScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final favoritos = context.watch<FavoritosNotifier>();
    final todas = context.watch<PrevisaoNotifier>().localidades;
    final lista = todas.where((l) => favoritos.contem(l.id)).toList();

    if (lista.isEmpty) {
      return const EstadoVazio(mensagem: 'Marca uma localidade com a estrela para a veres aqui.');
    }
    return RefreshIndicator(
      onRefresh: () => context.read<FavoritosNotifier>().carregar(),
      child: ListView(
        children: [
          for (final l in lista)
            ListTile(
              title: Text(l.nome),
              subtitle: Text(l.ilha),
              trailing: BotaoFavorito(localidadeId: l.id),
              onTap: () => context.push('/localidade/${l.id}'),
            ),
        ],
      ),
    );
  }
}

5. Logout: apagar token e cache

class SessaoNotifier extends ChangeNotifier {
  SessaoNotifier(this._storage, this._db, this._favoritos);
  final TokenStorage _storage;
  final BaseDados _db;
  final FavoritosNotifier _favoritos;

  Future<void> terminarSessao() async {
    await _storage.apagar();            // 1. token fora do Keychain/Keystore
    await _db.apagarTudo();             // 2. cache que pode ter dados do grupo
    _favoritos.limpar();                // 3. estado em memória
    notifyListeners();                  // 4. o router leva ao ecrã de entrada
  }
}

• Ordem: primeiro o que é sensível (token), depois o que é grande (cache), depois a memória. Se a app for morta a meio, o token já não existe.
• Com refresh token haveria um passo 0: POST /v1/auth/revoke no servidor. Um token que só se apaga no cliente continua válido até expirar.
• O go_router observa o SessaoNotifier via refreshListenable e o redirect manda para /entrar quando não há sessão.

Até amanhã