Os caminhos alternativos do Touch ID são seguros para aprovações de agentes?

Os fluxos de aprovação pelo Touch ID falham de maneiras comuns: a tampa do laptop está fechada, o teclado externo não é do tipo certo, o sensor não reconhece o dedo ou o macOS bloqueia a biometria depois de várias tentativas malsucedidas. Se um agente puder transformar essas condições em um estado de aprovação ambíguo, o sistema já cometeu o erro perigoso. O caminho alternativo precisa dizer se a ação ainda está pendente, foi definitivamente negada ou aguarda um evento separado de autenticação.

Isso parece um problema de interface até o momento em que um agente mantém uma capacidade SSH ou prepara uma solicitação de API autenticada. Então cada estado vago vira comportamento operacional. Um agente não entende «tente novamente mais tarde» se o gateway não lhe der um resultado preciso. As pessoas também tomam decisões ruins quando o único sinal é uma solicitação biométrica insistente e uma solicitação que pode ou não continuar ativa.

A regra de projeto que sigo é simples: uma falha biométrica pode atrasar uma solicitação, mas nunca amplia a autoridade. Um sensor ausente pode mudar o caminho para uma decisão humana, mas nunca permite que o agente escolha uma alternativa mais fraca. Um cofre de credenciais bloqueado interrompe o trabalho baseado em segredos até que o mecanismo declarado seja aberto novamente.

A disponibilidade do Touch ID não é a mesma coisa que aprovação

O Touch ID responde se o macOS consegue verificar uma pessoa por meio de um sensor biométrico neste momento. Aprovação responde se essa pessoa verificada autoriza este processo do agente ou esta ação proposta. Tratar os dois como um único evento cria comportamentos alternativos ruins, porque as causas da falha pertencem a camadas diferentes.

Uma aprovação por sessão pode ser uma decisão humana simples: a pessoa lê a identidade do processo solicitante e aceita ou rejeita a execução. Uma aprovação por chamada pergunta novamente porque o proprietário da credencial marcou aquela chave como sensível o bastante para exigir isso. Nenhuma dessas decisões diz que um cofre de credenciais criptografado está disponível. O cofre pode continuar bloqueado, o Mac pode estar na tela de login ou o sensor físico pode estar inacessível.

O Sallyport mantém essa separação de forma prática. Seu mecanismo do cofre é absoluto: enquanto o cofre está bloqueado, toda ação é negada. A autorização por sessão e as chaves por chamada decidem apenas a autoridade do agente depois que esse mecanismo permite uma ação. Assim, um cartão de aprovação agradável não pode virar uma porta dos fundos para contornar um cofre bloqueado.

Essa distinção também evita uma recomendação comum e descuidada: «Se o Touch ID falhar, basta mostrar um botão de aprovação normal». Isso pode estar correto para uma solicitação de autorização humana criada para permitir um clique. Está errado se a solicitação Touch ID que falhou é justamente o que protege o acesso a um cofre de credenciais. A mesma tela pode conter os dois conceitos, mas eles precisam produzir mudanças de estado diferentes.

Use estados separados também no protocolo do agente:

• awaiting_human_approval significa que a ação não foi executada e uma pessoa pode aprovar ou rejeitar a solicitação identificada.
• awaiting_vault_unlock significa que a ação não pode prosseguir porque a barreira de segredos está fechada.
• denied significa que o gateway não manterá autoridade para essa solicitação.
• expired significa que a solicitação esperou tempo demais e precisa ser proposta novamente.

Não chame os quatro estados de «aprovação necessária». Essa expressão esconde o fato mais importante para o agente: se ele deve esperar, parar ou preparar uma nova solicitação.

O modo clamshell remove o sensor integrado

Fechar a tampa de um MacBook torna fisicamente inacessível o sensor Touch ID integrado. A Apple cita o modo clamshell como o exemplo atual de sensor biométrico integrado inacessível no macOS: um MacBook fechado e conectado a um monitor e teclado externos não pode usar seu sensor Touch ID interno, a menos que o teclado externo tenha Touch ID.

Esse comportamento não é um caso raro para quem executa agentes de programação. O MacBook fica sob a mesa ou ao lado do monitor justamente porque permanece ligado por longos períodos. Se o desenho da aprovação pressupõe que a pessoa consegue alcançar o botão de ligar, ele funcionará durante uma demonstração e falhará no uso normal.

Mapeie a configuração da mesa antes de decidir o comportamento alternativo:

A palavra importante nessa tabela é «pode». A presença do hardware não prova que ele está utilizável. Um teclado sem fio pode estar desligado, desconectado, emparelhado com outro computador ou simplesmente indisponível para a sessão atual. O aplicativo deve perguntar ao sistema operacional se a política solicitada pode ser executada antes de mostrar uma mensagem mandando alguém tocar em um sensor.

Não transforme automaticamente o modo clamshell em motivo para reduzir uma ação de aprovação por chamada para aprovação por sessão. Essa mudança dura além do problema físico e concede um escopo mais amplo do que o que a pessoa viu. Se a solicitação exige uma decisão por chamada, mantenha-a como tal. Mostre uma aprovação por clique se esse controle permitir, ou faça a ação esperar ou falhar de acordo com sua classe.

Existe uma diferença prática entre «a pessoa não consegue fazer uma leitura» e «a pessoa não consegue aprovar». Alguém com um teclado externo comum ainda pode ler um cartão e clicar em um botão de aprovação. Isso basta para uma chave por chamada criada para aprovação por um clique ou Touch ID. Não desbloqueia um cofre protegido pelo Touch ID. A linguagem na tela também deve ser direta: «Aprovação disponível, cofre bloqueado» é muito melhor do que um banner vermelho genérico de falha.

Uma leitura malsucedida deve manter uma única solicitação, não criar nova autoridade

Uma leitura de impressão digital malsucedida é normal. Pele seca, ângulo ruim do dedo, resíduos no sensor e um toque apressado acontecem. A resposta correta é um estado de nova tentativa limitado, não uma negação imediata nem uma solicitação ativa sem fim.

A documentação de LocalAuthentication da Apple distingue uma falha simples de autenticação do bloqueio biométrico. Uma verificação de credencial malsucedida informa authenticationFailed; o bloqueio é um estado separado depois de muitas tentativas sem sucesso. O gateway deve preservar essa distinção porque os caminhos de recuperação são diferentes.

Em uma leitura comum malsucedida, mantenha a ação original imutável e pendente por um curto intervalo. A pessoa deve ver o que está aprovando, qual processo do agente solicitou, o host ou a API de destino, o rótulo da credencial e a operação relevante. O agente deve receber um resultado pendente legível por máquina, e não um timeout disfarçado de falha.

Uma resposta útil pode ter este formato:

{
  "status": "awaiting_human_approval",
  "request_id": "apr_7f3c",
  "reason": "biometric_retry",
  "expires_at": "2026-07-22T18:42:00Z",
  "retry_after_ms": 1500,
  "action_started": false
}

O request_id precisa estar vinculado à ação proposta completa, não apenas à credencial. Se um agente pedir para executar git push e depois mudar o remoto, a branch ou o comando enquanto a pessoa tenta novamente o Touch ID, ele criou uma solicitação diferente. Rejeite-a ou exija um novo cartão de aprovação. Reutilizar uma aprovação porque o mesmo processo ainda existe é como novas tentativas inofensivas se transformam em um problema de agente confuso.

Defina dois limites. Primeiro, limite as tentativas na interface para impedir que um agente defeituoso reabra continuamente solicitações que exigem atenção. Segundo, faça a solicitação pendente expirar após um período curto e visível. Uma pessoa que volta dez minutos depois deve decidir sobre uma solicitação renderizada novamente, porque o estado do repositório, o conteúdo da API ou o sistema remoto podem ter mudado.

O estado de nova tentativa não deve manter material de credencial no processo do agente. O agente pode manter o comando pretendido ou o corpo da solicitação, mas o gateway não deve entregar um token «enquanto espera» a autenticação. A injeção do segredo só acontece quando o gateway executa a operação aprovada pelo canal.

É aqui que as equipes muitas vezes colocam o loop de nova tentativa no lugar errado. Elas deixam o agente repetir toda a chamada da ferramenta a cada poucos segundos. Isso produz cartões duplicados, aumenta a chance de operações de API repetidas e ensina ao modelo que insistir é uma forma de contornar a hesitação. O gateway é responsável pela solicitação pendente. O agente consulta ou aguarda esse request ID. Ele não cria novas solicitações até que a primeira expire ou seja negada.

O bloqueio do sensor significa que o caminho biométrico terminou

O bloqueio do sensor não é uma solicitação que precisa de outra impressão digital. É o macOS informando que a biometria está desativada até que a pessoa faça a recuperação exigida pelo sistema operacional. A Apple documenta biometryLockout como o estado alcançado depois de muitas tentativas malsucedidas e informa que uma senha é necessária para desbloquear a biometria.

Isso tem uma consequência direta para as ações do agente: pare de solicitar Touch ID. Uma caixa de diálogo que continua pedindo uma impressão digital depois que o sistema operacional bloqueou o sensor é enganosa e pode levar as pessoas a pressioná-lo repetidamente. Informe que o macOS exige autenticação da conta para restaurar o Touch ID e encerre ou suspenda a solicitação do gateway de acordo com a classe da ação.

Não trate silenciosamente a senha da conta como equivalente ao Touch ID. A política deviceOwnerAuthentication da Apple pode usar Touch ID, um Apple Watch emparelhado nas proximidades ou a senha do macOS. A política exclusiva para biometria, por outro lado, falha quando a biometria está indisponível, não foi configurada ou está bloqueada. As duas são políticas válidas do sistema, mas fazem promessas de segurança diferentes.

Se o mecanismo do seu cofre diz que o Touch ID é a barreira, o fallback para senha muda essa barreira. Você pode decidir que a senha do macOS é um autenticador alternativo aceitável em outro desenho de produto, mas precisa declarar e implementar essa escolha na fronteira do cofre. Não a herde por acidente apenas porque um framework oferece um padrão conveniente.

Para um cofre vinculado ao Touch ID, o bloqueio deve produzir um resultado operacional terminal para cada chamada baseada em segredos que esteja aguardando:

status: denied
reason: vault_authentication_unavailable
recovery: autentique-se no macOS para restaurar o Touch ID e envie uma nova solicitação
action_started: false

Isso é intencionalmente mais rigoroso do que uma leitura temporariamente malsucedida. A pessoa precisa concluir uma recuperação fora do fluxo de aprovação do gateway. Manter a solicitação antiga ativa durante essa recuperação cria uma ambiguidade ruim: a entrada posterior da senha da conta autorizou o comando SSH original ou apenas restaurou o sensor? Torne a resposta inequívoca. Ela restaurou o sensor. O agente precisa solicitar a operação novamente.

Para aprovações que não dependem do desbloqueio do cofre, você pode escolher outro resultado. Um cartão de autorização por sessão pode continuar disponível como uma decisão por clique se o desenho permitir e se a ação não precisar de um segredo bloqueado. A interface deve dizer exatamente o que falhou. «Touch ID bloqueado, aprovação por clique ainda disponível» é uma mensagem coerente. «Falha de autenticação» não é.

Faça esperar ou parar ser uma propriedade da ação

Não decida se deve esperar apenas com base no código de erro. Decida a partir da consequência da ação, da necessidade de atualidade e do estado da fronteira de credenciais. O mesmo sensor indisponível pode fazer uma consulta de status inofensiva esperar, um comando irreversível de infraestrutura parar e uma solicitação baseada em cofre falhar até que o cofre seja desbloqueado.

Uso três classes de ação.

Classe um: aguardar uma breve resposta humana

Aguarde uma ação somente quando todas estas afirmações forem verdadeiras:

• O gateway ainda não iniciou a operação nem injetou uma credencial.
• A solicitação tem uma identidade estável e um prazo visível.
• Repeti-la depois da aprovação não surpreenderá a pessoa, porque o destino e o conteúdo permanecem fixos.
• A ação é reversível, somente de leitura ou idempotente o bastante para que um breve atraso não altere seu significado.

Exemplos incluem ler a versão de um pacote privado, buscar as configurações da branch protegida de um repositório ou fazer uma solicitação de API de simulação claramente identificada. Mesmo nesses casos, a espera pertence ao gateway, não ao loop de novas tentativas do agente.

Classe dois: parar e exigir uma nova solicitação

Pare quando o atraso mudar o significado prático do comando. Uma implantação, uma migração de banco de dados de produção, um force push, uma rotação de credenciais, a captura de um pagamento ou um comando SSH que exclui dados não deve ficar aguardando com uma aprovação latente. A pessoa que o vir mais tarde merece um novo cartão que reflita o contexto atual.

Pare também se a solicitação incluir valores efêmeros. Uma solicitação de API assinada, um artefato de implantação de uso único, uma URL de curta duração ou um comando cujo diretório de trabalho local tenha mudado não deve ser retomado a partir de uma intenção antiga. O gateway não pode saber que o agente ainda quer dizer a mesma coisa apenas porque o processo não terminou.

Classe três: negar imediatamente porque o cofre está fechado

Um cofre bloqueado tem prioridade sobre a conveniência. Se a chamada HTTP ou o comando SSH proposto exige um segredo armazenado e o mecanismo do cofre está bloqueado, negue a ação em vez de colocá-la em fila para execução automática depois do desbloqueio. A pessoa pode desbloquear o cofre e então o agente pode enviar uma nova solicitação. Isso preserva um registro causal claro: desbloquear primeiro, propor depois, executar por último.

É aqui que a escada fixa de decisões do Sallyport é útil. Seu mecanismo do cofre nega todas as ações enquanto está bloqueado; depois, a autorização por sessão e a aprovação por chamada se aplicam à solicitação. Não há linguagem de política tentando presumir que um curl atrasado é inofensivo o bastante para ser ressuscitado após um evento biométrico.

A alternativa tentadora é uma fila de execução que acorda quando a pessoa toca no sensor. Ela é popular porque torna as demonstrações mais suaves. No uso real, transforma a autenticação em um gatilho para um trabalho que talvez já não seja desejado. A aprovação deve liberar uma solicitação que a pessoa ainda possa ver, não esvaziar uma fila montada enquanto ela estava ausente.

Teclados externos com Touch ID precisam de uma verificação de disponibilidade

Um teclado externo com Touch ID resolve um problema do modo clamshell, mas acrescenta outra dependência. O teclado precisa estar presente e utilizável na sessão ativa do Mac quando a aprovação ocorrer. Trate isso como uma condição atual, não como um fato de configuração verificado uma única vez.

Os erros de LocalAuthentication da Apple incluem biometryDisconnected e biometryNotPaired para acessórios biométricos removíveis. Esses códigos importam porque distinguem hardware ausente de uma pessoa que não conseguiu se autenticar. Um teclado desconectado nunca deve consumir uma tentativa nem contar para a taxa de falhas do usuário.

A interface e o protocolo devem responder de forma diferente a quatro estados:

Não mostre nomes brutos de erros do framework à pessoa, mas mantenha-os no registro local de atividade. «Teclado externo com Touch ID indisponível» é útil. LAError.biometryDisconnected pertence aos diagnósticos e testes.

O cartão de aprovação também precisa continuar operável sem o sensor. Isso é uma questão de segurança e de usabilidade básica. Mouse, trackpad, foco do teclado e controles de acessibilidade ainda devem permitir que alguém rejeite uma solicitação ou escolha uma aprovação por clique permitida. Um sensor biométrico inacessível nunca deve prender alguém em uma solicitação sem resposta possível.

A tela de aprovação precisa nomear a barreira bloqueada

A maior parte da confusão vem de um único modal genérico que tenta representar todas as formas de autenticação. Separe a mensagem de acordo com a barreira que está aguardando.

Para uma solicitação por sessão, mostre primeiro a autoridade de assinatura de código do processo solicitante e depois ofereça uma escolha clara de aprovar ou rejeitar. É nesse momento que a pessoa decide se aquela execução do agente pode operar. Se o Touch ID estiver disponível, ele pode confirmar a escolha. Se o desenho permitir um clique, o modo clamshell não deve transformar o cartão em um beco sem saída.

Para uma chave por chamada, mostre a ação exata e o rótulo da credencial. Uma aprovação por clique ainda é uma decisão por chamada somente se se aplicar a uma única solicitação imutável e expirar rapidamente. Não permita que um agente agrupe cinco chamadas atrás de um único botão apenas porque o Touch ID é inconveniente naquela mesa.

Para um cofre bloqueado, diga que o cofre está bloqueado e que a ação não começou. Não apresente a mensagem como uma solicitação do agente rejeitada, porque a pessoa pode achar que precisa clicar novamente. A recuperação pertence ao mecanismo de autenticação declarado do cofre. Depois que ele abrir, exija uma nova solicitação para qualquer ação que precise do segredo.

Um bom registro de auditoria separa essas transições. Por exemplo:

2026-07-22T18:40:12Z request.created     id=apr_7f3c channel=ssh action="git push origin main"
2026-07-22T18:40:13Z approval.pending   id=apr_7f3c method=touch_id
2026-07-22T18:40:16Z biometric.failed   id=apr_7f3c source=built_in_sensor
2026-07-22T18:41:02Z request.expired    id=apr_7f3c action_started=false

O log da ação não deve fingir que uma leitura malsucedida foi uma negação de autorização. Foi uma tentativa de autenticação malsucedida. A solicitação expirou sem execução. Essas palavras importam durante uma análise, especialmente quando um agente afirma que «não conseguiu fazer a implantação» e a pessoa responsável precisa saber se o sistema o bloqueou, se o usuário o rejeitou ou se ninguém concluiu a solicitação.

Em sistemas de auditoria à prova de adulteração, registre a transição de estado antes de retorná-la ao agente. O Sallyport projeta seus diários Sessions e Activity a partir de um único log criptografado e encadeado por hash, e seu comando sp audit verify verifica essa cadeia offline sobre o texto cifrado. Isso fornece a um revisor posterior evidências de que uma solicitação expirou ou foi negada, sem exigir confiança na própria transcrição do agente.

Teste a mesa física, não apenas a API do caminho feliz

Um teste unitário de LocalAuthentication que retorna códigos de sucesso e falha é necessário, mas quase não prova nada sobre um fluxo de aprovação. As falhas que frustram as pessoas aparecem quando configuração do hardware, estado da área de trabalho e tempo do agente se encontram.

Execute esta sequência em um Mac real antes de considerar o fluxo concluído:

1. Inicie uma sessão do agente com o laptop aberto, envie uma solicitação por chamada, rejeite-a e depois envie uma nova solicitação e aprove-a. Confirme que a solicitação rejeitada nunca é executada.
2. Feche a tampa e conecte um monitor externo e um teclado sem Touch ID. Confirme que a interface não pede que a pessoa toque em um sensor inacessível. Teste uma aprovação por clique e uma solicitação baseada no cofre.
3. Repita com um teclado Touch ID externo funcionando. Desconecte-o ou desligue-o enquanto uma aprovação estiver pendente. Confirme que a solicitação informa hardware indisponível, e não uma tentativa biométrica malsucedida.
4. Faça várias leituras malsucedidas até o macOS entrar em bloqueio. Confirme que as solicitações biométricas param, que as solicitações baseadas em segredos não ficam em fila para execução posterior e que a recuperação exige uma ação enviada novamente.
5. Deixe uma solicitação pendente expirar. Mude a branch do repositório, os argumentos do comando ou o conteúdo da API antes de enviar uma nova solicitação. Confirme que a nova proposta recebe um request ID diferente e uma nova decisão humana.

Verifique os logs após cada execução. Você deve encontrar um evento de criação da solicitação, uma sequência de mudanças de estado e um único evento de execução, ou nenhum. Várias execuções após um único sinal de aprovação indicam um defeito de repetição ou replay. A ausência de um evento terminal significa que a equipe de suporte terá de adivinhar se o agente ainda está esperando.

Teste também o cancelamento. A pessoa deve poder rejeitar enquanto o Touch ID está indisponível, o agente deve poder abandonar uma solicitação pendente e o encerramento do aplicativo deve invalidar aprovações ativas. A Apple distingue cancelamento pelo usuário, pelo aplicativo e pelo sistema no LocalAuthentication. Seu modelo de auditoria deve preservar essa distinção, mesmo que a interface os agrupe sob uma mensagem simples de «cancelado».

Um caminho alternativo confiável parece quase entediante quando funciona. A tela diz a verdade sobre o sensor, o agente recebe um estado que pode obedecer, os segredos permanecem no cofre e nenhuma ação escapa porque alguém fechou a tampa do laptop. Esse é o padrão a manter: toda falha física leva a um resultado específico, sem ampliação de autoridade.