INÍCIO RÁPIDO
Seu primeiro plugin
A CLI cria um exemplo que consulta o manifesto de atualização do MDM pelo gateway do Titan. O teste injeta o transporte local e pode rodar sem uma conta do Titan Continuum ou um banco configurado.
-
Baixe e confira o arquivo
Salve o ZIP e o arquivo SHA-256 na mesma pasta. Execute a verificação antes de extrair. Os passos seguintes usam o diretório
titanArchitect-sdkextraído do ZIP.Terminalsha256sum -c titan-architect-sdk.zip.sha256 unzip titan-architect-sdk.zip -
Gere a estrutura e execute o teste
Tenha PHP 8.2+, Python 3 e as ferramentas da linguagem escolhida. Rode da pasta que contém
titanArchitect-sdk. Usedoctorpara verificar o ambiente antes de gerar o projeto.PHP 8.2+ com Composer. A biblioteca local é
zerotrusted/forge-sdk.Terminal · PHPphp titanArchitect-sdk/tools/titan-sdk.php doctor php php titanArchitect-sdk/tools/titan-sdk.php init php empresa.atualizacoes ./empresa-atualizacoes (cd empresa-atualizacoes && composer install) php titanArchitect-sdk/tools/titan-sdk.php test ./empresa-atualizacoesNode.js 22+ com npm. A distribuição inclui a biblioteca local
@zerotrusted/forge-sdkcompilada.Terminal · TypeScriptphp titanArchitect-sdk/tools/titan-sdk.php doctor typescript php titanArchitect-sdk/tools/titan-sdk.php init typescript empresa.atualizacoes-web ./empresa-atualizacoes-web (cd empresa-atualizacoes-web && npm install) php titanArchitect-sdk/tools/titan-sdk.php test ./empresa-atualizacoes-web -
Troque a operação
Mude o ponto de entrada em
src/, declare no manifesto a dependência e as permissões da operação desejada e ajuste o teste. Verifique também o caso de acesso negado e a resposta a um erro de transporte.
Estrutura e manifesto
O manifesto externo v1 usa um ID como empresa.atualizacoes. O prefixo titan. é reservado aos módulos do Titan Continuum. Incremente a versão a cada alteração do conteúdo assinado.
| Arquivo | PHP | TypeScript |
|---|---|---|
| Entrada | src/plugin.php | src/plugin.ts compila para dist/plugin.js |
| Dependências | composer.json | package.json, tsconfig.json |
| Teste | tests/plugin.php | tests/plugin.cjs |
| Identidade | manifest.json com versão, linguagem, permissões, eventos e dependências | |
{
"id": "empresa.atualizacoes",
"version": "1.0.0",
"runtime": "php",
"entrypoint": "src/plugin.php",
"apiVersion": 1,
"dependencies": ["titan.downloads"],
"permissions": ["downloads.read_release"],
"events": []
}
Para TypeScript, use "runtime": "typescript" e "entrypoint": "dist/plugin.js". Declare somente as capacidades necessárias. Uma declaração no manifesto precisa de autorização correspondente na instalação e para o ator.
Validação pelo terminal
A referência da CLI lista comandos, argumentos e códigos de saída, do diagnóstico à verificação da assinatura.
Rode o validador na pasta que contém o SDK e seus projetos. A mesma ferramenta aceita manifestos de PHP e TypeScript. Ela lê a estrutura e confere os arquivos informados antes do empacotamento.
php titanArchitect-sdk/tools/titan-sdk.php validate \
./empresa-atualizacoes manifest.json src/plugin.php
(cd empresa-atualizacoes-web && npm run build)
php titanArchitect-sdk/tools/titan-sdk.php validate \
./empresa-atualizacoes-web manifest.json dist/plugin.js
Sem a lista de arquivos, a validação inclui o manifesto e a entrada que ele declara. Para entregar recursos de interface ou módulos auxiliares, informe os caminhos relativos que serão adicionados ao FEX. Para validar arquivos JavaScript, deixe o Node.js disponível no PATH. A ferramenta usa node --check para verificar a sintaxe dos arquivos .js, .cjs e .mjs incluídos. Um resultado válido mostra a identidade, a versão e o runtime. Um erro faz o comando terminar com um código diferente de zero.
Use o validador como uma etapa de CI após os testes. Execute composer test no PHP ou npm test no TypeScript para verificar o comportamento com o transporte de teste. A verificação do FEX assinado confere assinatura, integridade e limites do arquivo final.
Gateway e contratos
O host fornece o canal autenticado e associa ao plugin a identidade, as permissões e o ator. A operação recebe apenas dados de negócio. O SDK valida a versão, o identificador da resposta e o formato do resultado.
use Forge\Client;
use Forge\JsonTransport;
$transport = new JsonTransport($exchange);
$client = new Client(Closure::fromCallable($transport));
$release = $client->call('downloads.release_manifest', ['app' => 'mdm']);
import { Client, jsonTransport } from '@zerotrusted/forge-sdk';
const client = new Client(jsonTransport(exchange));
const release = await client.call('downloads.release_manifest', { app: 'mdm' });
exchange recebe e devolve uma string JSON. No TypeScript a resposta é assíncrona. Em IPC, o protocolo usa uma mensagem delimitada por LF, até 64 KiB por mensagem, e uma chamada por vez em cada canal. Reserve stdout ao protocolo e envie logs a stderr.
{"version":1,"id":"req-01","operation":"downloads.release_manifest","input":{"app":"mdm"}}
{"version":1,"id":"req-01","ok":false,"error":{"code":"forbidden"}}
A referência completa está em contracts/service-call.schema.json, incluída no ZIP. Em falhas, preserve o ID de correlação. Para uma gravação sem confirmação, consulte o resultado da operação ou use a chave de idempotência prevista pelo serviço antes de decidir se deve tentar de novo.
Integração com o núcleo
Plugin nativo
Código revisado junto ao Titan Continuum, registrado em titansource/plugins/native/. Pode declarar controladores, navegação, permissões, bibliotecas, esquemas e um provedor de serviços.
Extensão externa
Usa o SDK no seu processo e é revisada como FEX. Sua integração com o Titan depende de canal autenticado e supervisor configurados no host. A seleção no catálogo registra a versão escolhida.
Rotas, navegação e permissões
No checkout do Titan Continuum, coloque o código nativo em titansource/plugins/native/pendencias e declare empresa.pendencias em manifest.json. O manifesto a seguir associa a rota a um controlador privado e declara o menu exibido para usuários com a permissão.
{
"id": "empresa.pendencias",
"name": "Pendências",
"version": "1.0.0",
"apiVersion": 1,
"runtime": "php",
"entrypoint": "schema.php",
"routes": {"ext-pendencias/index": "acessos"},
"controllers": {"ext-pendencias/index": "index.php"},
"permissions": {
"Pendências": {"plugin_pendencias.acessar": "Consultar pendências"}
},
"navigation": [{
"path": "ext-pendencias/index",
"label": "Pendências",
"icon": "clipboard-list",
"badge": "",
"requires": ["plugin_pendencias.acessar"]
}],
"schemas": {"empresa_pendencias": 1}
}
O catálogo da Administração incorpora as permissões declaradas. Nos controladores, valide sessão, ação, permissão, escopo e CSRF para gravações. Ao converter um módulo existente, preserve a URL, a forma da resposta, o tópico e a autorização.
Comunicação entre plugins
Declare o provedor em dependencies. O plugin que possui a regra expõe operações por serviceProvider, cada uma com uma permissão explícita. Consuma essas operações usando o SDK, com identidade e autorização fornecidas pelo host.
Se dois módulos nativos precisam compartilhar um arquivo, stream ou a mesma transação, o provedor pode expor o código em libraries. O consumidor chama titanArchitectLoadDependencyLibrary($caller, $provider, $library) depois de declarar a dependência. O gateway JSON é a interface para runtimes externos.
Banco e migrações
Um plugin nativo pode criar e evoluir as tabelas que possui pelo migrador. Use o serviço responsável para acessar dados de outro plugin ou do núcleo. A tabela de versões registra as chaves históricas e a versão aplicada, por isso preserve as chaves de migrações já implantadas.
use Titan\Architect\Core\NativeMigrations;
NativeMigrations::apply($pdo, 'empresa.pendencias', 'empresa_pendencias', static function () use ($pdo): void {
$pdo->exec('CREATE TABLE IF NOT EXISTS empresa_pendencias (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
referencia VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4');
});
Execute migrações antes das transações de negócio. No MySQL, DDL pode confirmar transações de forma implícita. Teste o upgrade em banco isolado, prefira mudanças aditivas e confira backup e restauração.
| Tabelas do núcleo | Finalidade |
|---|---|
users, access_permissions, access_permission_history | Identidades, concessões e histórico de acesso. |
user_admin_promotions, user_manager_tags, user_manager_tag_history | Promoções administrativas, marcações de gestor e auditoria. |
user_menu_groups, user_settings, user_presence | Preferências de interface e presença. |
security_events, security_login_limits, system_lockdown | Auditoria, limites de autenticação e política de bloqueio. |
password_reset_tokens, password_reset_limits, security_email_queue | Recuperação de credenciais e fila de e-mails de segurança. |
internal_terms_documents, internal_terms_acceptances, internal_terms_attempts | Documentos, aceites e tentativas dos termos internos. |
titan_devices, titan_device_events, titan_device_enrollment_limits, titan_device_policy, titan_device_policy_events, titan_device_browser_sessions | Políticas, vínculo de dispositivos e sessões de navegador. |
app_schema_versions, request_receipts, realtime_events | Versões de esquema, deduplicação e notificações do transporte. |
architect_packages, architect_package_selection, architect_package_audit | Versões registradas, seleção e trilha de auditoria FEX. |
architect_event_outbox | Fila transacional de eventos do Architect com isolamento por empresa. |
A lista de referências de implementação está em docs/NUCLEO-TITAN.md. Extensões externas usam serviços autorizados e armazenamentos isolados.
Eventos e entregas
O produtor registra o evento na mesma transação que confirma a operação. Guarde ID estável, tipo, versão, empresa, instante e correlação. O publicador confiável adquire uma reserva temporária de entrega e confirma somente após a persistência pelo consumidor.
O consumidor deve deduplicar pelo ID ao processar novas tentativas. O SDK possui helpers de evento e a fila tem testes isolados. O adaptador de entrega precisa ser configurado no host antes de usar a fila operacionalmente.
Kit de interface
Adapte o painel de versões Android ao seu plugin. A prévia tem filtros combinados, ordenação, detalhes de pacote, tema e suporte a teclado e telas pequenas.
Abrir a demonstração · Consultar os componentes
| Arquivo | Finalidade |
|---|---|
design/painel.php | Renderiza a tabela, as métricas e os detalhes com dados demonstrativos. |
design/plugin.css | Define componentes, tokens e layouts com estilos limitados à interface do plugin. |
design/plugin.js | Adiciona filtros, ordenação, cópia de hash e tema sem bibliotecas externas. |
php -S 127.0.0.1:8000 -t titanArchitect-sdk/design
Abra http://127.0.0.1:8000/painel.php no navegador. Use os projetos de referência para exercitar o contrato da consulta de versões em PHP e TypeScript.
Compatibilidade
Ao migrar um módulo existente, registre quais URLs, métodos, tópicos e permissões os clientes já usam. Mapeie os aliases públicos para controladores do plugin e preserve os formatos de requisição e resposta.
O ZIP inclui compatibilidade/README.md com o roteiro de migração e compatibilidade/rotas.json com um mapa de exemplo. Use apiVersion, routes, permissions e schema para registrar o contrato da instalação. Mantenha o mapa ao lado dos testes de regressão e use o manifest.json para as declarações do plugin.
Valide as duas entradas
Teste uma chamada pelo endereço antigo e outra pelo atual. Compare permissões, códigos HTTP, tópicos WebSocket, payloads, efeitos no banco, arquivos e dependências dos workers. Faça a prova com um usuário autorizado e outro sem acesso.
Empacote e assine o FEX
Use o empacotador incluído no SDK com PHP e as extensões zip e sodium. Ele gera um ZIP com manifest.json, os arquivos selecionados, files.sha256 e signature.sig.
php titanArchitect-sdk/tools/titan-sdk.php pack \
./empresa-atualizacoes ./empresa-atualizacoes.fex /caminho/privado/publicador.secret \
manifest.json src/plugin.php
Para TypeScript, use o diretório do projeto compilado e inclua dist/plugin.js no lugar de src/plugin.php. Inclua na lista os demais arquivos usados em execução. A chave privada Ed25519 bruta de 64 bytes fica fora do projeto e do pacote. Entregue para homologação a chave pública correspondente de 32 bytes.
Limites do pacote
Até 250 MB (262.144.000 bytes) no ZIP, 1 GiB expandido, 512 arquivos e 128 KiB por arquivo de metadados. Use caminhos relativos e nomes distintos, inclusive quando comparados sem distinguir maiúsculas de minúsculas. O verificador também aplica limites de compactação.
O índice canônico tem um SHA-256 hexadecimal minúsculo, dois espaços, caminho e LF por linha. Os caminhos são ordenados byte a byte. O índice e sua assinatura ficam fora da lista de hashes. signature.sig contém a assinatura Ed25519 dos bytes exatos do índice.
Homologação e ciclo de versões
No Titan Continuum, o Plugin Manager fica em Administração → Plugins e exige a permissão developer. O responsável pela instalação cadastra a chave pública do publicador em um diretório privado de confiança.
- Verificar. Envie o FEX assinado, selecione o publicador e confira o SHA-256, o manifesto e as dependências mostradas.
- Aprovar. Registre os bytes revisados. Uma mesma versão identifica sempre o mesmo conteúdo.
- Selecionar. Registre a versão para a instalação. Execução de extensões externas, conexão com o gateway e entrega de eventos dependem da integração do host.
- Voltar uma versão ou desativar. Selecione uma versão aprovada anterior ou limpe a seleção. A exclusão da versão do catálogo conserva a trilha de auditoria.
Nos plugins nativos, a alteração de código segue o deploy do Titan Continuum. Valide URLs antigas, permissões, respostas HTTP e WebSocket, reconexão, gravações, migrações e preservação dos anexos antes de publicar. A restauração deve abranger a aplicação e os serviços afetados.
Diagnóstico
Composer ou npm não encontra o SDK local
Mantenha o checkout extraído do SDK na posição usada ao gerar o projeto. Se mover a pasta, ajuste a configuração repositories do Composer ou a dependência file: no package.json. No TypeScript, compile o SDK antes de instalar o consumidor.
O gateway retornou forbidden
Confira as três decisões de acesso envolvidas na chamada. Verifique se a permissão está declarada no manifesto, concedida à instalação e liberada ao ator autenticado. Confirme também a dependência do serviço chamado.
O gateway retornou unknown_operation ou invalid_input
Confirme o nome e a versão da operação publicada, além da instalação do provedor. Compare as propriedades enviadas com o contrato e envie um objeto JSON em input.
A verificação do FEX falhou
Compare o hash do arquivo recebido com o revisado. Confirme o par de chaves, a lista de arquivos distribuídos, a versão do manifesto e o caminho da entrada. Gere outro arquivo assinado quando os bytes mudarem.
O pacote está selecionado, mas não há processo em execução
Verifique se a instalação oferece supervisor e canal autenticado para a extensão. O registro de seleção e a auditoria podem existir antes de qualquer processo do plugin.