DOCUMENTAÇÃO DO SDK CONTRATO V1 · REFERÊNCIA ATUAL

Contrato v1 do host

Esta referência integra o portal Titan Arch Developer. O SDK V2 preserva este protocolo; comece pelo ambiente Linux ou explore o Studio 0.2.0.

O contrato v1 distribuído usa Client.call(...). Supervisão de runtimes externos e eventos duráveis exigem homologação da instalação. Desenvolva plugins para o ecossistema Titan em PHP e TypeScript. Execute os projetos de referência, adapte a interface e valide o FEX assinado antes de distribuir.

Bibliotecas, CLI, kit de interface e projetos de referênciaSHA-256

empresa.atualizacoes / plugin.ts
import type { Client } from
  '@zerotrusted/forge-sdk';

export const run = (client: Client) =>
  client.call('downloads.release_manifest', {
    app: 'mdm'
  });
CATÁLOGO Módulos nativos Consulte fluxos, permissões, dependências e contratos dos módulos do Titan. Abrir catálogo LINHA DE COMANDO CLI do SDK Gere e teste seu plugin. Assine, inspecione e verifique o pacote FEX. Ver comandos

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.

  1. 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-sdk extraído do ZIP.

    Terminal
    sha256sum -c titan-architect-sdk.zip.sha256
    unzip titan-architect-sdk.zip
  2. 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. Use doctor para verificar o ambiente antes de gerar o projeto.

    PHP 8.2+ com Composer. A biblioteca local é zerotrusted/forge-sdk.

    Terminal · PHP
    php 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-atualizacoes

    Node.js 22+ com npm. A distribuição inclui a biblioteca local @zerotrusted/forge-sdk compilada.

    Terminal · TypeScript
    php 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
  3. 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.

ArquivoPHPTypeScript
Entradasrc/plugin.phpsrc/plugin.ts compila para dist/plugin.js
Dependênciascomposer.jsonpackage.json, tsconfig.json
Testetests/plugin.phptests/plugin.cjs
Identidademanifest.json com versão, linguagem, permissões, eventos e dependências
manifest.json · PHP
{
  "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.

Terminal · PHP
php titanArchitect-sdk/tools/titan-sdk.php validate \
  ./empresa-atualizacoes manifest.json src/plugin.php
Terminal · TypeScript
(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.

PHP
use Forge\Client;
use Forge\JsonTransport;

$transport = new JsonTransport($exchange);
$client = new Client(Closure::fromCallable($transport));
$release = $client->call('downloads.release_manifest', ['app' => 'mdm']);
TypeScript
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.

JSON · requisição v1
{"version":1,"id":"req-01","operation":"downloads.release_manifest","input":{"app":"mdm"}}
JSON · resposta de acesso negado
{"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.

manifest.json · nativo aprovado
{
  "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.

PHP · versão declarada em schemas
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úcleoFinalidade
users, access_permissions, access_permission_historyIdentidades, concessões e histórico de acesso.
user_admin_promotions, user_manager_tags, user_manager_tag_historyPromoções administrativas, marcações de gestor e auditoria.
user_menu_groups, user_settings, user_presencePreferências de interface e presença.
security_events, security_login_limits, system_lockdownAuditoria, limites de autenticação e política de bloqueio.
password_reset_tokens, password_reset_limits, security_email_queueRecuperação de credenciais e fila de e-mails de segurança.
internal_terms_documents, internal_terms_acceptances, internal_terms_attemptsDocumentos, 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_sessionsPolíticas, vínculo de dispositivos e sessões de navegador.
app_schema_versions, request_receipts, realtime_eventsVersões de esquema, deduplicação e notificações do transporte.
architect_packages, architect_package_selection, architect_package_auditVersões registradas, seleção e trilha de auditoria FEX.
architect_event_outboxFila 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

ArquivoFinalidade
design/painel.phpRenderiza a tabela, as métricas e os detalhes com dados demonstrativos.
design/plugin.cssDefine componentes, tokens e layouts com estilos limitados à interface do plugin.
design/plugin.jsAdiciona filtros, ordenação, cópia de hash e tema sem bibliotecas externas.
Terminal · prévia local
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.

Terminal · projeto PHP
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.

  1. Verificar. Envie o FEX assinado, selecione o publicador e confira o SHA-256, o manifesto e as dependências mostradas.
  2. Aprovar. Registre os bytes revisados. Uma mesma versão identifica sempre o mesmo conteúdo.
  3. 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.
  4. 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.