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.

Quando o participante é uma empresa, definir preserveSensitiveData: true no evento força a identidade dele a privada — name, taxId, taxIdType e as coordenadas do endereço são suprimidos — enquanto o evento em si permanece publicamente visível.

Omitir o campo não é o mesmo que enviar false. A superfície pública de MassID da Carrot publica o nome de um participante apenas quando o evento ACTOR carrega isPublic: true e preserveSensitiveData: false explicitamente. A verificação é !== false, então um campo ausente equivale a true e o nome é retido sem gerar erro. Envie a flag explicitamente em todo evento ACTOR, qualquer que seja a decisão.

Mesmo com as duas flags definidas, alguns papéis nunca são nomeados nessa superfície — Waste Generator, Hauler e Bin Custodian são retidos independentemente disso — então defini-las não garante a publicação.

preserveSensitiveData não é o mesmo que isPublic: false, que remove o evento inteiro da linha do tempo pública e, portanto, da rastreabilidade pública. Use preserveSensitiveData quando a etapa operacional precisa continuar visível mas o participante por trás dela não.

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 e do reciclador devem ser públicos.
• Dados do gerador e do transportador — informações da empresa, endereços, PII, placas de veículos — devem ser privados.
• Campos de texto livre nunca devem conter dados sensíveis, independentemente da visibilidade do evento.

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