Privacidade e Mascaramento

A plataforma Carrot foi projetada para tornar a logística da cadeia de suprimentos transparente e publicamente verificável. No entanto, alguns dados são sensíveis por razões comerciais ou de privacidade. Este guia cobre os controles de privacidade disponíveis nos níveis de documento e metadados de eventos.

As flags de visibilidade são definidas ao criar um documento (veja API de Documents) e podem ser ajustadas por meio de eventos UPDATE (veja Especificação de Eventos).

Controles de visibilidade

• isPublic: controla se os dados são visíveis em superfícies públicas como o Carrot Registry.
• isPubliclySearchable: controla se os registros podem ser encontrados por meio de busca pública.

O flag isPublic aparece em quatro níveis no caminho de escrita, e é obrigatório em cada um deles:

• Nível do documento — isPublic na criação do documento, controlando o próprio documento.
• Nível do evento — isPublic em cada evento, controlando a visibilidade do evento inteiro.
• Nível do anexo — isPublic em cada entrada do array attachments do evento, que é o que governa as linhas de anexo na tabela abaixo.
• Nível do atributo de metadados — isPublic em cada entrada de metadata.attributes, que sobrepõe a visibilidade do evento para aquele atributo.

Níveis mais baixos podem sobrepor níveis mais altos — por exemplo, um atributo pode ser marcado como privado dentro de um evento público. A precedência é aplicada pela plataforma Carrot.

Os objetos target e updates carregam o próprio isPublic para o documento que criam ou modificam. O relatedDocument.isPublic é diferente: ele controla se o evento espelhado gravado no documento relacionado é público, não a visibilidade daquele documento. É obrigatório quando bidirectional é true.

Quando um documento ou evento é marcado como público (isPublic: true), qualquer pessoa com o ID do documento pode visualizá-lo no Carrot Registry (registry.carrot.eco). Quando privado (isPublic: false), os dados ficam ocultos da visualização pública, mas permanecem acessíveis a auditores para verificação de conformidade.

Identidade do participante

As flags de visibilidade governam o evento e seus metadados. A identidade do participante por trás do evento é governada separadamente por preserveSensitiveData, um campo true/false aceito em todo evento.

A visibilidade de um participante é decidida uma vez para o documento inteiro, a partir de todos os eventos que o mencionam. Quando o participante é uma empresa, definir preserveSensitiveData: true em qualquer um desses eventos força a identidade dele a privada em todo o documento — name, taxId, taxIdType e as coordenadas do endereço são suprimidos — enquanto os eventos em si permanecem publicamente visíveis. Município e estado não são suprimidos.

Envie o campo explicitamente em todo evento ACTOR. Use false para Processadores, Recicladores e Integradores, e true para Geradores de Resíduos, transportadores, Gestores de Resíduos e todos os demais papéis da cadeia de suprimentos. Um participante que é ao mesmo tempo transportador e processador ou reciclador no mesmo documento é a exceção: deixe o campo de fora em todo evento que o menciona, e ele pode ser nomeado na página pública do documento. Deixar o campo de fora aplica o padrão do papel: Processadores, Recicladores e Integradores podem ser nomeados, desde que todo papel da cadeia de suprimentos que o participante ocupa no documento seja um desses, com uma exceção para transportadores descrita abaixo; os demais papéis da cadeia de suprimentos não são nomeados por padrão. true em qualquer evento ACTOR mantém o participante sem nome em todas as superfícies públicas.

A superfície pública de MassID da Carrot é mais restrita. Entre outras condições, ela exige isPublic: true em todo evento ACTOR que nomeia o participante e, entre os papéis da cadeia de suprimentos, nomeia apenas Processadores, Recicladores e Integradores: um participante que ocupa qualquer outro papel da cadeia no documento nunca é nomeado ali, independentemente das flags.

Um papel que pode ser nomeado é, portanto, permissão, não garantia. Envie as flags que este guia especifica e depois leia o documento publicado para ver o resultado, em vez de prevê-lo a partir do papel. Se um nome que você esperava não aparecer, confira antes aquele payload contra este guia — o papel, o isPublic do evento e o preserveSensitiveData. Quando os três corresponderem ao que o guia pede, a retenção é decisão da superfície, e não algo a perseguir mudando flags; portanto, não construa lógica de exibição que presuma que um papel que pode ser nomeado aparece nomeado.

As duas flags respondem a perguntas diferentes, e confundi-las é o erro mais caro desta página:

• isPublic decide se o evento é publicado. Um evento ACTOR enviado como isPublic: false sai inteiramente da linha do tempo pública — a etapa desaparece, não apenas o nome — e é apontado em auditoria, porque todo evento ACTOR deve ser público.
• preserveSensitiveData decide se o participante por trás do evento é nomeado. A etapa continua na linha do tempo; a empresa por trás dela não aparece.

Manter um participante sem nome é trabalho de preserveSensitiveData. Nunca é trabalho de isPublic: false.

O campo também é aceito em relatedDocument, onde é rejeitado quando bidirectional é false — assim como eventName e eventLabel, já que não há evento espelhado a descrever.

Política de visibilidade por papel

Os seguintes padrões se aplicam a todas as metodologias:

• Dados do Processador, do Reciclador e do Integrador devem ser públicos.
• Dados do gerador e do transportador — informações da empresa, endereços, PII — devem ser privados.
• Um participante que é ao mesmo tempo o transportador e o reciclador ou processador no mesmo documento segue o padrão do reciclador ou processador e pode ser nomeado na página pública do documento.
• Na página pública do documento, transportadores, custodiantes de ponto de coleta e Gestores de Resíduos não são nomeados por padrão: os papéis aparecem enquanto os nomes ficam retidos, e enviar preserveSensitiveData: false os nomeia ali. A superfície pública de MassID da Carrot nunca nomeia um Gerador de Resíduos, transportador, custodiante de ponto de coleta ou Gestor de Resíduos, independentemente das flags.
• Campos de texto livre nunca devem conter dados sensíveis, independentemente da visibilidade do evento.

O Gestor de Resíduos é retido por risco de reidentificação, não porque a participação dele seja sensível em si. Ele é contratado por um gerador para escolher a destinação, então onde ele atende um único gerador em um município, nomeá-lo nomeia aquele gerador — e município e estado são públicos.

Quando um participante acumula vários papéis

Participantes rotineiramente acumulam mais de um papel: um transportador com sua própria instalação de triagem é transportador e Processador, e um reciclador que também tria é Processador e Reciclador. A flag é enviada por evento, mas uma empresa resolve para uma única resposta no documento inteiro.

• Envie preserveSensitiveData: true em todo evento ACTOR de Gerador de Resíduos ou transportador. Um único true em qualquer lugar do documento já torna aquele participante privado por todo ele, então enviar de forma consistente não custa nada.
• O caso a considerar é uma empresa que é seu transportador e seu Reciclador ou Processador. Ela segue o padrão do Reciclador ou Processador na página pública do documento, então esconder a aparição dela como transportadora não protege nada: deixe o campo de fora em todo evento que a menciona. Um único true ali sobrepõe a exceção e torna a empresa privada em todo o documento.
• O Gerador de Resíduos nunca é afetado por esse caso. Ele permanece privado, faça o que fizer no mesmo documento.

A ordem completa de resolução, vencendo a primeira que se aplicar:

1. preserveSensitiveData: true em qualquer ocorrência → privado em todo o documento.
2. Gerador de Resíduos → privado. A regra 3 nunca se aplica a ele.
3. Transportador junto com Reciclador ou Processador → público.
4. preserveSensitiveData: false em qualquer ocorrência → público.
5. O padrão do papel; papéis que discordam resolvem como privado.

Para recomendações específicas por metodologia, siga os flags isPublic nos exemplos canônicos:

• BOLD Recycling — Referência de Eventos do MassID
• BOLD Carbon — Referência de Eventos do MassID

Tratamento de dados sensíveis

Para atributos de metadados que contêm dados sensíveis ou pessoais (ex.: placas de veículos, identificadores de motoristas), você tem duas opções:

• Privacidade total — Defina isPublic: false para ocultar os dados completamente das superfícies públicas.
• Mascaramento parcial — Envie o valor completo, defina isPublic: true e defina sensitive: true nos metadados. A plataforma aplica mascaramento nas superfícies públicas — uma placa enviada como ABC-1234 aparece como AB****34 — enquanto preserva o valor completo para auditores.

O mascaramento sempre cobre um único trecho contíguo no meio do valor: no mínimo 4 caracteres e no mínimo metade do valor, deixando no máximo 8 caracteres visíveis, divididos entre o início e o fim.

Apenas valores string são mascarados. Um atributo não-string marcado como sensitive é tratado como privado, e seu valor é omitido inteiramente das superfícies públicas.

Não pré-mascare ou redija valores no seu payload. Envie os dados completos e deixe a plataforma realizar o mascaramento.

O sensitive é um sinal que você envia, não o mecanismo que mantém um valor fora das superfícies públicas da própria Carrot. A API pública de MassID e o documento de metadados do registry publicam um conjunto fixo de atributos mantido no código da Carrot, então um atributo que você acrescenta não é publicado lá, com ou sem a flag. Defina a flag corretamente mesmo assim — é ela que governa o mascaramento na página pública do documento — mas não a trate como a garantia.

Veja Formatos de Dados para o atributo sensitive e as convenções de formato de mascaramento.

Padrões comuns de dados privados

A tabela a seguir lista campos de dados que parceiros comumente configuram como privados, junto com a justificativa para cada um:

Se você não tem certeza se um campo deve ser privado ou usar mascaramento parcial, consulte o time Carrot para orientação específica ao seu caso de uso.

Estratégia prática de mascaramento

1. Mantenha valores sensíveis privados por padrão.
2. Exponha apenas os campos mínimos exigidos pelo seu negócio e fluxos públicos.
3. Use sensitive: true para campos que precisam ser publicamente visíveis de forma mascarada.
4. Audite payloads públicos regularmente para garantir que não haja exposição não intencional de dados.

Referências relacionadas:

• Conceitos Fundamentais — Visibilidade e privacidade
• API de Events
• Formatos de Dados