neovault 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# neovault
+
+SDK, CLI e servidor MCP oficiais do **NeoVault** — cofre de identidade, consentimento e comportamento pseudonimizado (LGPD by design). Os sistemas consomem dados pessoais por API com finalidade auditada, em vez de guardar o próprio cadastro.
+
+```sh
+npm install neovault
+```
+
+## SDK
+
+```ts
+import { NeoVault } from 'neovault';
+
+const nv = new NeoVault({ token: process.env.NEOVAULT_TOKEN!, purpose: 'atendimento' });
+
+const { id_nome } = await nv.identities.register({
+  nome: 'Maria Silva', cpf: '52998224725', dataNascimento: '1990-01-01',
+});
+await nv.contacts.upsert('minha-loja', id_nome, {
+  celular: '+5585999998888', canalPref: 'whatsapp', optinMkt: true,
+});
+const perfil = await nv.prefs.profile('minha-loja', id_nome); // pseudonimizado, sem PII
+
+// Opt-in em grupo: aprovação ÚNICA para uma rede nomeada de empresas
+await nv.optin.aprovar('rede-neovault', { idNome: id_nome, evidencia: 'termo-v1:hash:...' });
+
+// Eliminação LGPD (crypto-shredding + cascata automática)
+await nv.identities.shred(id_nome);
+```
+
+## CLI
+
+```sh
+export NEOVAULT_TOKEN=<jwt do realm>
+npx neovault health
+npx neovault identity resolve --id <id_nome> --purpose atendimento
+npx neovault optin aprovar --grupo rede-neovault --id <id_nome> --evidencia termo-v1
+npx neovault help
+```
+
+Operadores emitem tokens com `EXT_JWT_SECRET=<segredo> npx neovault mint --sub eduuw --scopes contact:read,prefs:read --tenants eduue`.
+
+## MCP (agentes)
+
+```json
+{
+  "mcpServers": {
+    "neovault": {
+      "command": "npx",
+      "args": ["-y", "--package=neovault", "neovault-mcp"],
+      "env": { "NEOVAULT_TOKEN": "<jwt do realm>" }
+    }
+  }
+}
+```
+
+Ferramentas: `vault_register/resolve/shred`, `contact_upsert/get`, `optin_aprovar/revogar/status`, `prefs_profile`, `qsa_pessoa/empresa`.
+
+## Tokens e escopos
+
+JWT HS256 do realm NeoVault com escopos mínimos: `vault:register|resolve|shred`, `contact:read|write|delete`, `optin:read|write|admin`, `prefs:read`, `qsa:read|write` — e tenants autorizados. Peça o seu ao operador em https://neovault.com.br.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * CLI do NeoVault. Env:
+ *   NEOVAULT_TOKEN   JWT do realm (obrigatório, exceto `mint`)
+ *   NEOVAULT_API     base da API (default https://api.neovault.com.br)
+ *   EXT_JWT_SECRET   segredo do realm (só para `mint` — operador)
+ */
+import { parseArgs } from 'node:util';
+import { NeoVault, NeoVaultError } from './client.js';
+import { decode, mint } from './mint.js';
+const USAGE = `neovault <comando> [opções]
+
+  mint      --sub <sistema> --scopes a,b [--tenants x,y] [--purpose p] [--ttl 3600]
+  whoami
+  health
+  identity  register --nome N --cpf C --nascimento YYYY-MM-DD [--source s]
+            resolve  --id <id_nome> [--purpose p]
+            shred    --id <id_nome> [--purpose p]
+  contact   get|delete --tenant T --id <id_nome>
+            upsert --tenant T --id <id_nome> [--celular +55...] [--email e] --canal whatsapp|email|sms [--optin]
+  optin     grupo    --grupo G [--descricao D]
+            membro   --grupo G --tenant T [--encerrar]
+            aprovar  --grupo G --id <id_nome> --evidencia E
+            revogar  --grupo G --id <id_nome>
+            status   --grupo G --id <id_nome>
+  prefs     profile --tenant T --id <id_nome>
+  qsa       pessoa  --id <id_nome>
+            empresa --cnpj C [--todos]
+
+Env: NEOVAULT_TOKEN, NEOVAULT_API, EXT_JWT_SECRET (mint).`;
+function die(msg) {
+    console.error(msg);
+    process.exit(1);
+}
+function out(v) {
+    console.log(typeof v === 'string' ? v : JSON.stringify(v ?? { ok: true }, null, 2));
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    const sub = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
+    const flags = parseArgs({
+        args: argv.slice(sub ? 2 : 1),
+        options: {
+            sub: { type: 'string' }, scopes: { type: 'string' }, tenants: { type: 'string' },
+            purpose: { type: 'string' }, ttl: { type: 'string' },
+            nome: { type: 'string' }, cpf: { type: 'string' }, nascimento: { type: 'string' },
+            source: { type: 'string' }, id: { type: 'string' }, tenant: { type: 'string' },
+            celular: { type: 'string' }, email: { type: 'string' }, canal: { type: 'string' },
+            optin: { type: 'boolean' }, grupo: { type: 'string' }, descricao: { type: 'string' },
+            evidencia: { type: 'string' }, encerrar: { type: 'boolean' },
+            cnpj: { type: 'string' }, todos: { type: 'boolean' },
+        },
+        strict: true,
+    }).values;
+    if (!cmd || cmd === 'help' || cmd === '--help')
+        return void console.log(USAGE);
+    if (cmd === 'mint') {
+        const secret = process.env.EXT_JWT_SECRET ?? die('EXT_JWT_SECRET não definido (segredo vem do cofre, nunca de flag)');
+        if (!flags.sub || !flags.scopes)
+            die('mint exige --sub e --scopes');
+        return void out(mint(secret, {
+            sub: flags.sub, scopes: flags.scopes.split(','),
+            tenants: flags.tenants?.split(','), purpose: flags.purpose,
+            ttlSeconds: flags.ttl ? Number(flags.ttl) : undefined,
+        }));
+    }
+    const token = process.env.NEOVAULT_TOKEN ?? die('NEOVAULT_TOKEN não definido');
+    if (cmd === 'whoami')
+        return void out(decode(token) ?? die('token ilegível'));
+    const nv = new NeoVault({ token, baseUrl: process.env.NEOVAULT_API, purpose: flags.purpose, source: flags.source });
+    const need = (v, n) => v ?? die(`--${n} é obrigatório`);
+    switch (`${cmd} ${sub ?? ''}`.trim()) {
+        case 'health': return void out((await nv.health()) ? 'online' : 'fora do ar');
+        case 'identity register':
+            return void out(await nv.identities.register({
+                nome: need(flags.nome, 'nome'), cpf: need(flags.cpf, 'cpf'),
+                dataNascimento: need(flags.nascimento, 'nascimento'), source: flags.source,
+            }));
+        case 'identity resolve': return void out(await nv.identities.resolve(need(flags.id, 'id'), flags.purpose));
+        case 'identity shred': return void out(await nv.identities.shred(need(flags.id, 'id'), flags.purpose));
+        case 'contact get': return void out(await nv.contacts.get(need(flags.tenant, 'tenant'), need(flags.id, 'id')));
+        case 'contact delete': return void out(await nv.contacts.delete(need(flags.tenant, 'tenant'), need(flags.id, 'id')));
+        case 'contact upsert':
+            return void out(await nv.contacts.upsert(need(flags.tenant, 'tenant'), need(flags.id, 'id'), {
+                celular: flags.celular, email: flags.email, canalPref: need(flags.canal, 'canal'), optinMkt: !!flags.optin,
+            }));
+        case 'optin grupo': return void out(await nv.optin.upsertGrupo(need(flags.grupo, 'grupo'), flags.descricao));
+        case 'optin membro':
+            return void out(await nv.optin.setMembro(need(flags.grupo, 'grupo'), need(flags.tenant, 'tenant'), !flags.encerrar));
+        case 'optin aprovar':
+            return void out(await nv.optin.aprovar(need(flags.grupo, 'grupo'), {
+                idNome: need(flags.id, 'id'), evidencia: need(flags.evidencia, 'evidencia'),
+            }));
+        case 'optin revogar': return void out(await nv.optin.revogar(need(flags.grupo, 'grupo'), need(flags.id, 'id')));
+        case 'optin status': return void out(await nv.optin.status(need(flags.grupo, 'grupo'), need(flags.id, 'id')));
+        case 'prefs profile': return void out(await nv.prefs.profile(need(flags.tenant, 'tenant'), need(flags.id, 'id')));
+        case 'qsa pessoa': return void out(await nv.qsa.vinculosDaPessoa(need(flags.id, 'id')));
+        case 'qsa empresa': return void out(await nv.qsa.qsaDaEmpresa(need(flags.cnpj, 'cnpj'), !flags.todos));
+        default: die(USAGE);
+    }
+}
+main().catch((err) => {
+    if (err instanceof NeoVaultError)
+        die(`${err.message}\n${JSON.stringify(err.body)}`);
+    die(String(err?.message ?? err));
+});

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * NeoVault SDK — cliente da borda F6-lite (https://api.neovault.com.br).
+ *
+ * Browser-safe (fetch nativo, zero dependências). O token é um JWT HS256 do
+ * realm NeoVault com escopos mínimos — emita com a CLI (`neovault mint`) ou
+ * peça ao operador.
+ *
+ *   const nv = new NeoVault({ token });
+ *   const { id_nome } = await nv.identities.register({ nome, cpf, dataNascimento: '1990-01-01' });
+ *   await nv.contacts.upsert('minha-loja', id_nome, { celular: '+5585...', canalPref: 'whatsapp', optinMkt: true });
+ */
+export interface NeoVaultOptions {
+    /** JWT do realm NeoVault (escopos mínimos do seu caso de uso). */
+    token: string;
+    /** Base da API. Default: produção. */
+    baseUrl?: string;
+    /** Finalidade LGPD padrão das leituras (audita no cofre). */
+    purpose?: string;
+    /** Proveniência dos dados gravados (ex.: "declarado", "import:legacy"). */
+    source?: string;
+    fetch?: typeof fetch;
+}
+export declare class NeoVaultError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+export interface Identity {
+    id_nome: string;
+    nome: string;
+    cpf: string;
+    data_nascimento: string;
+}
+export interface Contact {
+    tenant: string;
+    id_nome: string;
+    celular?: string;
+    email?: string;
+    canal_pref: string;
+    optin_mkt: boolean;
+    source: string;
+}
+export interface Aprovacao {
+    aprovacao_id: number;
+    grupo: string;
+    tenants: string[];
+    evidencia: string;
+    aprovado_at: string;
+    vigente: boolean;
+}
+export interface Profile {
+    tenant: string;
+    faixa_etaria?: string;
+    regiao?: string;
+    segmento?: string;
+    eventos: {
+        tipo: string;
+        payload: Record<string, unknown>;
+        source: string;
+        at: string;
+    }[];
+}
+export interface Vinculo {
+    id_nome: string;
+    cnpj: string;
+    vinculo: 'socio' | 'administrador';
+    qualificacao?: string;
+    source: string;
+    valido_de: string;
+    valido_ate?: string;
+    vigente: boolean;
+}
+export declare class NeoVault {
+    readonly baseUrl: string;
+    private readonly opts;
+    private readonly f;
+    constructor(opts: NeoVaultOptions);
+    private req;
+    /** Identidade civil (cofre de PII). Escopos: vault:register|resolve|shred. */
+    readonly identities: {
+        register: (p: {
+            nome: string;
+            cpf: string;
+            dataNascimento: string;
+            source?: string;
+        }) => Promise<{
+            id_nome: string;
+        }>;
+        /** Leitura de PII — a finalidade é obrigatória e auditada. */
+        resolve: (idNome: string, purpose?: string) => Promise<Identity>;
+        /** Eliminação LGPD (crypto-shredding + cascata em todos os módulos). */
+        shred: (idNome: string, purpose?: string) => Promise<void>;
+    };
+    /** Contato por tenant (consentimento por controlador). Escopos: contact:*. */
+    readonly contacts: {
+        upsert: (tenant: string, idNome: string, p: {
+            celular?: string;
+            email?: string;
+            canalPref: string;
+            optinMkt: boolean;
+        }) => Promise<Contact>;
+        get: (tenant: string, idNome: string) => Promise<Contact>;
+        delete: (tenant: string, idNome: string) => Promise<void>;
+    };
+    /** Opt-in em grupo — aprovação única para uma rede nomeada. Escopos: optin:*. */
+    readonly optin: {
+        upsertGrupo: (grupo: string, descricao?: string) => Promise<{
+            grupo: string;
+        }>;
+        setMembro: (grupo: string, tenant: string, ativo?: boolean) => Promise<void>;
+        /** Aprovação única: fan-out automático de opt-in nos tenants membros. */
+        aprovar: (grupo: string, p: {
+            idNome: string;
+            evidencia: string;
+        }) => Promise<{
+            aprovacao_id: number;
+            aplicados: string[];
+            sem_contato: string[] | null;
+        }>;
+        /** Revogação única: saída automática exatamente do conjunto aprovado. */
+        revogar: (grupo: string, idNome: string) => Promise<{
+            aprovacao_id: number;
+            revogados: string[] | null;
+        }>;
+        status: (grupo: string, idNome: string) => Promise<Aprovacao>;
+    };
+    /** Perfil comportamental pseudonimizado do tenant. Escopo: prefs:read. */
+    readonly prefs: {
+        profile: (tenant: string, idNome: string) => Promise<Profile>;
+    };
+    /** Vínculos societários (fato global). Escopos: qsa:read|write. */
+    readonly qsa: {
+        upsertVinculo: (p: {
+            idNome: string;
+            cnpj: string;
+            vinculo: "socio" | "administrador";
+            qualificacao?: string;
+            validoDe: string;
+            validoAte?: string;
+        }) => Promise<Vinculo>;
+        encerrar: (p: {
+            idNome: string;
+            cnpj: string;
+            vinculo: "socio" | "administrador";
+            validoAte?: string;
+        }) => Promise<Vinculo>;
+        vinculosDaPessoa: (idNome: string) => Promise<Vinculo[]>;
+        qsaDaEmpresa: (cnpj: string, vigentes?: boolean) => Promise<Vinculo[]>;
+    };
+    /** Health da borda (sem auth). */
+    health(): Promise<boolean>;
+}

package/dist/client.js

@@ -0,0 +1,123 @@
+/**
+ * NeoVault SDK — cliente da borda F6-lite (https://api.neovault.com.br).
+ *
+ * Browser-safe (fetch nativo, zero dependências). O token é um JWT HS256 do
+ * realm NeoVault com escopos mínimos — emita com a CLI (`neovault mint`) ou
+ * peça ao operador.
+ *
+ *   const nv = new NeoVault({ token });
+ *   const { id_nome } = await nv.identities.register({ nome, cpf, dataNascimento: '1990-01-01' });
+ *   await nv.contacts.upsert('minha-loja', id_nome, { celular: '+5585...', canalPref: 'whatsapp', optinMkt: true });
+ */
+export class NeoVaultError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `NeoVault API: HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'NeoVaultError';
+    }
+}
+export class NeoVault {
+    baseUrl;
+    opts;
+    f;
+    constructor(opts) {
+        if (!opts.token)
+            throw new Error('NeoVault: token é obrigatório');
+        this.opts = opts;
+        this.baseUrl = (opts.baseUrl ?? 'https://api.neovault.com.br').replace(/\/$/, '');
+        this.f = opts.fetch ?? fetch;
+    }
+    async req(method, path, body, headers) {
+        const h = {
+            Authorization: `Bearer ${this.opts.token}`,
+            ...headers,
+        };
+        if (this.opts.purpose && !h['X-LGPD-Purpose'])
+            h['X-LGPD-Purpose'] = this.opts.purpose;
+        if (this.opts.source && !h['X-Data-Source'])
+            h['X-Data-Source'] = this.opts.source;
+        if (body !== undefined)
+            h['Content-Type'] = 'application/json';
+        const res = await this.f(`${this.baseUrl}${path}`, {
+            method,
+            headers: h,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            /* 204 / sem corpo */
+        }
+        if (!res.ok) {
+            const msg = parsed?.error;
+            throw new NeoVaultError(res.status, parsed, msg ? `NeoVault API: ${msg} (HTTP ${res.status})` : undefined);
+        }
+        return parsed;
+    }
+    /** Identidade civil (cofre de PII). Escopos: vault:register|resolve|shred. */
+    identities = {
+        register: (p) => this.req('POST', '/vault/v1/identities', {
+            nome: p.nome,
+            cpf: p.cpf,
+            data_nascimento: p.dataNascimento,
+        }, p.source ? { 'X-Data-Source': p.source } : undefined),
+        /** Leitura de PII — a finalidade é obrigatória e auditada. */
+        resolve: (idNome, purpose) => this.req('GET', `/vault/v1/identities/${idNome}`, undefined, purpose ? { 'X-LGPD-Purpose': purpose } : undefined),
+        /** Eliminação LGPD (crypto-shredding + cascata em todos os módulos). */
+        shred: (idNome, purpose) => this.req('DELETE', `/vault/v1/identities/${idNome}`, undefined, purpose ? { 'X-LGPD-Purpose': purpose } : undefined),
+    };
+    /** Contato por tenant (consentimento por controlador). Escopos: contact:*. */
+    contacts = {
+        upsert: (tenant, idNome, p) => this.req('PUT', `/contact/v1/tenants/${tenant}/contacts/${idNome}`, {
+            celular: p.celular ?? '',
+            email: p.email ?? '',
+            canal_pref: p.canalPref,
+            optin_mkt: p.optinMkt,
+        }),
+        get: (tenant, idNome) => this.req('GET', `/contact/v1/tenants/${tenant}/contacts/${idNome}`),
+        delete: (tenant, idNome) => this.req('DELETE', `/contact/v1/tenants/${tenant}/contacts/${idNome}`),
+    };
+    /** Opt-in em grupo — aprovação única para uma rede nomeada. Escopos: optin:*. */
+    optin = {
+        upsertGrupo: (grupo, descricao = '') => this.req('PUT', `/contact/v1/grupos/${grupo}`, { descricao }),
+        setMembro: (grupo, tenant, ativo = true) => this.req(ativo ? 'PUT' : 'DELETE', `/contact/v1/grupos/${grupo}/membros/${tenant}`, ativo ? {} : undefined),
+        /** Aprovação única: fan-out automático de opt-in nos tenants membros. */
+        aprovar: (grupo, p) => this.req('POST', `/contact/v1/grupos/${grupo}/aprovacoes`, { id_nome: p.idNome, evidencia: p.evidencia }),
+        /** Revogação única: saída automática exatamente do conjunto aprovado. */
+        revogar: (grupo, idNome) => this.req('DELETE', `/contact/v1/grupos/${grupo}/aprovacoes/${idNome}`),
+        status: (grupo, idNome) => this.req('GET', `/contact/v1/grupos/${grupo}/aprovacoes/${idNome}`),
+    };
+    /** Perfil comportamental pseudonimizado do tenant. Escopo: prefs:read. */
+    prefs = {
+        profile: (tenant, idNome) => this.req('GET', `/prefs/v1/tenants/${tenant}/profiles/${idNome}`),
+    };
+    /** Vínculos societários (fato global). Escopos: qsa:read|write. */
+    qsa = {
+        upsertVinculo: (p) => this.req('PUT', '/qsa/v1/vinculos', {
+            id_nome: p.idNome,
+            cnpj: p.cnpj,
+            vinculo: p.vinculo,
+            qualificacao: p.qualificacao ?? '',
+            valido_de: p.validoDe,
+            valido_ate: p.validoAte ?? '',
+        }),
+        encerrar: (p) => this.req('POST', '/qsa/v1/vinculos/encerrar', {
+            id_nome: p.idNome,
+            cnpj: p.cnpj,
+            vinculo: p.vinculo,
+            valido_ate: p.validoAte ?? '',
+        }),
+        vinculosDaPessoa: (idNome) => this.req('GET', `/qsa/v1/pessoas/${idNome}/vinculos`),
+        qsaDaEmpresa: (cnpj, vigentes = true) => this.req('GET', `/qsa/v1/empresas/${cnpj}/qsa${vigentes ? '' : '?vigentes=false'}`),
+    };
+    /** Health da borda (sem auth). */
+    async health() {
+        const res = await this.f(`${this.baseUrl}/healthz`);
+        return res.ok;
+    }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Servidor MCP do NeoVault (stdio) — expõe o cofre como ferramentas para
+ * agentes (Claude Code, etc.). Env: NEOVAULT_TOKEN (obrigatório), NEOVAULT_API.
+ *
+ * Config no cliente MCP:
+ *   { "command": "npx", "args": ["-y", "neovault-mcp"],
+ *     "env": { "NEOVAULT_TOKEN": "<jwt do realm>" } }
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { NeoVault, NeoVaultError } from './client.js';
+const token = process.env.NEOVAULT_TOKEN;
+if (!token) {
+    console.error('NEOVAULT_TOKEN não definido');
+    process.exit(1);
+}
+const nv = new NeoVault({ token, baseUrl: process.env.NEOVAULT_API, purpose: process.env.NEOVAULT_PURPOSE ?? 'mcp' });
+const server = new McpServer({ name: 'neovault', version: '0.1.0' });
+function wrap(fn) {
+    return async (args) => {
+        try {
+            const data = await fn(args);
+            return { content: [{ type: 'text', text: JSON.stringify(data ?? { ok: true }, null, 2) }] };
+        }
+        catch (err) {
+            const msg = err instanceof NeoVaultError ? `${err.message} ${JSON.stringify(err.body)}` : String(err);
+            return { content: [{ type: 'text', text: `erro: ${msg}` }], isError: true };
+        }
+    };
+}
+const idNome = z.string().uuid().describe('id_nome (token pseudônimo do titular)');
+const tenant = z.string().describe('tenant/controlador (slug, ex.: eduue)');
+server.registerTool('vault_register', {
+    description: 'Cadastra uma identidade civil no cofre; retorna o id_nome pseudônimo. PII nunca deve ser repetida na conversa.',
+    inputSchema: { nome: z.string(), cpf: z.string().describe('CPF, só dígitos'), data_nascimento: z.string().describe('YYYY-MM-DD') },
+}, wrap((a) => nv.identities.register({ nome: a.nome, cpf: a.cpf, dataNascimento: a.data_nascimento })));
+server.registerTool('vault_resolve', {
+    description: 'Resolve um id_nome para os dados civis (leitura auditada com finalidade LGPD).',
+    inputSchema: { id_nome: idNome, purpose: z.string().describe('finalidade LGPD da leitura') },
+}, wrap((a) => nv.identities.resolve(a.id_nome, a.purpose)));
+server.registerTool('vault_shred', {
+    description: 'Elimina a identidade (LGPD art. 18 VI): crypto-shredding + cascata automática em contatos/QSA/comportamento. IRREVERSÍVEL.',
+    inputSchema: { id_nome: idNome, purpose: z.string().optional() },
+}, wrap((a) => nv.identities.shred(a.id_nome, a.purpose)));
+server.registerTool('contact_upsert', {
+    description: 'Cria/atualiza o contato do titular em um tenant (consentimento por controlador; transição de opt-in é auditada).',
+    inputSchema: {
+        tenant, id_nome: idNome,
+        celular: z.string().optional().describe('E.164, ex.: +5585999998888'),
+        email: z.string().optional(),
+        canal_pref: z.enum(['whatsapp', 'email', 'sms']),
+        optin_mkt: z.boolean(),
+    },
+}, wrap((a) => nv.contacts.upsert(a.tenant, a.id_nome, { celular: a.celular, email: a.email, canalPref: a.canal_pref, optinMkt: a.optin_mkt })));
+server.registerTool('contact_get', {
+    description: 'Lê o contato do titular em um tenant.',
+    inputSchema: { tenant, id_nome: idNome },
+}, wrap((a) => nv.contacts.get(a.tenant, a.id_nome)));
+server.registerTool('optin_aprovar', {
+    description: 'Aprovação ÚNICA de opt-in para uma rede nomeada de empresas: entrada automática na lista de envio de todos os tenants membros, com prova auditada.',
+    inputSchema: { grupo: z.string().describe('slug da rede'), id_nome: idNome, evidencia: z.string().describe('referência SEM PII da prova (id de termo, hash)') },
+}, wrap((a) => nv.optin.aprovar(a.grupo, { idNome: a.id_nome, evidencia: a.evidencia })));
+server.registerTool('optin_revogar', {
+    description: 'Revogação única: saída automática da lista de envio exatamente nos tenants do snapshot aprovado.',
+    inputSchema: { grupo: z.string(), id_nome: idNome },
+}, wrap((a) => nv.optin.revogar(a.grupo, a.id_nome)));
+server.registerTool('optin_status', {
+    description: 'Consulta a aprovação vigente do titular na rede (snapshot, evidência, vigência).',
+    inputSchema: { grupo: z.string(), id_nome: idNome },
+}, wrap((a) => nv.optin.status(a.grupo, a.id_nome)));
+server.registerTool('prefs_profile', {
+    description: 'Perfil comportamental PSEUDONIMIZADO do titular no tenant (faixa etária, região, segmento, eventos) — sem PII, para personalização.',
+    inputSchema: { tenant, id_nome: idNome },
+}, wrap((a) => nv.prefs.profile(a.tenant, a.id_nome)));
+server.registerTool('qsa_pessoa', {
+    description: 'Lista os vínculos societários (empresas) de um titular.',
+    inputSchema: { id_nome: idNome },
+}, wrap((a) => nv.qsa.vinculosDaPessoa(a.id_nome)));
+server.registerTool('qsa_empresa', {
+    description: 'Lista o QSA (sócios/administradores) de uma empresa pelo CNPJ.',
+    inputSchema: { cnpj: z.string(), vigentes: z.boolean().optional().describe('default true') },
+}, wrap((a) => nv.qsa.qsaDaEmpresa(a.cnpj, a.vigentes ?? true)));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mint.d.ts

@@ -0,0 +1,21 @@
+export interface MintClaims {
+    /** id do sistema consumidor (ex.: "eduuw"). */
+    sub: string;
+    /** escopos mínimos (ex.: ["contact:read","prefs:read"]). */
+    scopes: string[];
+    /** tenants autorizados; ["*"] = todos (só operador). */
+    tenants?: string[];
+    /** finalidade LGPD padrão das leituras. */
+    purpose?: string;
+    /** vida útil em segundos (default 3600). */
+    ttlSeconds?: number;
+}
+/** Assina um JWT HS256 aceito pela borda F6-lite. */
+export declare function mint(secret: string, c: MintClaims): string;
+/** Decodifica o payload de um token (sem verificar assinatura — uso informativo). */
+export declare function decode(token: string): {
+    sub: string;
+    scopes: string[];
+    tenants?: string[];
+    exp: number;
+} | null;

package/dist/mint.js

@@ -0,0 +1,39 @@
+/**
+ * Emissão de tokens de sistema do realm NeoVault (HS256) — NODE-ONLY.
+ * O segredo NUNCA deve ir para código ou flags: leia de env/secret manager.
+ * Produção: a emissão pertence ao operador do realm.
+ */
+import { createHmac } from 'node:crypto';
+const b64url = (buf) => buf.toString('base64url');
+/** Assina um JWT HS256 aceito pela borda F6-lite. */
+export function mint(secret, c) {
+    if (!secret)
+        throw new Error('mint: secret é obrigatório (use env EXT_JWT_SECRET)');
+    if (!c.sub || !c.scopes?.length)
+        throw new Error('mint: sub e scopes são obrigatórios');
+    const now = Math.floor(Date.now() / 1000);
+    const head = b64url(Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })));
+    const payload = b64url(Buffer.from(JSON.stringify({
+        sub: c.sub,
+        scopes: c.scopes,
+        ...(c.tenants?.length ? { tenants: c.tenants } : {}),
+        ...(c.purpose ? { purpose: c.purpose } : {}),
+        iat: now,
+        exp: now + (c.ttlSeconds ?? 3600),
+    })));
+    const signed = `${head}.${payload}`;
+    const sig = b64url(createHmac('sha256', secret).update(signed).digest());
+    return `${signed}.${sig}`;
+}
+/** Decodifica o payload de um token (sem verificar assinatura — uso informativo). */
+export function decode(token) {
+    const parts = token.trim().split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "neovault",
+  "version": "0.1.0",
+  "description": "SDK, CLI e servidor MCP oficiais do NeoVault — cofre de identidade, consentimento e comportamento pseudonimizado (LGPD by design).",
+  "keywords": ["neovault", "lgpd", "identidade", "consentimento", "pii", "vault", "mcp"],
+  "homepage": "https://neovault.com.br",
+  "repository": { "type": "git", "url": "git+https://github.com/vertikon/neovault.com.br.git", "directory": "sdk/js" },
+  "license": "MIT",
+  "author": "Vertikon",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/client.d.ts", "default": "./dist/client.js" },
+    "./mint": { "types": "./dist/mint.d.ts", "default": "./dist/mint.js" }
+  },
+  "bin": { "neovault": "dist/cli.js", "neovault-mcp": "dist/mcp.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/client.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}