MÓDULO 1.3

🛂 Cross-origin e permissões

Modele origem, identidade, consentimento e fronteiras entre página, agente, backend e serviços externos.

6

Tópicos

3h

Carga

Agent Developer

Nível

Segurança

Tipo

0 de 60%
1

Mapeie quem fala por quem

O que é: Página, agente, usuário e backend possuem identidades e autoridades diferentes.

Por que aprender: Confundir essas identidades cria delegação excessiva e bugs de autorização.

Origem da página estado de partida Fronteira de permissão decisão observável Serviço autorizado resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

actor: userSession.id
agent: browserAgent.instanceId
origin: location.origin
resource: "enrollments"
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

principal

02

delegação

03

sessão

04

recurso

2

Use a política da mesma origem

O que é: Origem combina esquema, host e porta e define uma fronteira central da Web.

Por que aprender: Uma tool registrada por um documento não concede acesso livre a outras origens.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
const lifecycle = new AbortController();

await document.modelContext.registerTool(tool, {
  exposedTo: ["https://agent.example"],
  signal: lifecycle.signal
});

// Same-origin é o padrão. Cross-origin exige origem explícita e confiável.

Três controles diferentes

exposedTo seleciona origens autorizadas a descobrir a tool; a Permissions Policy tools controla delegação no documento; o backend ainda autentica a pessoa e autoriza cada efeito.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

same-origin

02

scheme

03

host

04

port

3

Trate iframe como fronteira

O que é: Frames incorporados possuem documento, origem e ciclo de vida próprios.

Por que aprender: O agente precisa saber qual contexto oferece a tool e onde o efeito será visível.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

const tools = await document.modelContext.getTools({
  fromOrigins: ["https://agent.example"]
});
const selected = tools.find((tool) => tool.name === "buscar_cursos");

// RegisteredTool preserva origem e Window do contexto registrador.
assertTrusted(selected.origin);
runOnlyWhileConnected(selected.window);
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

top frame

02

iframe

03

sandbox

04

context id

4

Não transforme CORS em autorização

O que é: CORS controla leitura por scripts no navegador; o backend ainda valida identidade e permissão.

Por que aprender: Uma resposta liberada por CORS pode continuar proibida para aquele usuário e operação.

CÓDIGO DE REFERÊNCIA

fetch(api, { credentials: "include", signal });
// servidor valida sessão, escopo e CSRF
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

CORS

02

credentials

03

backend auth

04

CSRF

5

Peça consentimento proporcional

O que é: Ações sensíveis exigem uma confirmação clara que mostre alvo, efeito e reversibilidade.

Por que aprender: Consentimento genérico ou antecipado não cobre uma mutação específica.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

confirm({ action: "cancelar inscrição", target: enrollmentId, reversible: false });
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

just in time

02

efeito

03

alvo

04

reversibilidade

6

Teste ataques entre contextos

O que é: A suíte cobre tool spoofing, navegação durante execução, frame removido e resposta de origem inesperada.

Por que aprender: Fronteiras só existem de verdade quando os caminhos adversariais são exercitados.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Desenhar uma matriz de autoridade para um agente que navega entre catálogo público, área autenticada e serviço externo.

Critério de Agent Developer responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

esperado: rejeitar resultado quando responseOrigin !== registeredOrigin
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

spoofing

02

navigation race

03

frame removal

04

origin check

📦 Entrega do módulo

Desenhar uma matriz de autoridade para um agente que navega entre catálogo público, área autenticada e serviço externo.

Critério de aceite

A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.

Evidência

Inclua código, cenário testado, resultado observado e uma limitação conhecida.

← Voltar para a trilhaPróximo módulo: 1.4 →

Fontes técnicas