feat(provider): add Gelios SDK package v2

infra/deploy-runner/build-platform-gelios-provider-v2-artifact.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { cp, lstat, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const platformRoot = resolve(here, '../..')
+const artifactRoot = resolve(process.env.NODEDC_DEPLOY_ARTIFACT_DIR || resolve(here, '../deploy-artifacts'))
+const [transitionId = '20260718-005', ...extra] = process.argv.slice(2)
+if (extra.length || !/^\d{8}-[0-9]{3}$/.test(transitionId)) {
+  throw new Error('usage: build-platform-gelios-provider-v2-artifact.mjs [YYYYMMDD-NNN]')
+}
+
+const id = `platform-gelios-provider-v2-${transitionId}`
+const target = join(artifactRoot, `nodedc-${id}.tgz`)
+const files = [
+  'platform/packages/external-provider-contract/providers/gelios/v2/README.md',
+  'platform/packages/external-provider-contract/providers/gelios/v2/index.mjs',
+  'platform/packages/external-provider-contract/providers/gelios/v2/package.mjs',
+]
+const expectedSha256 = new Map([
+  [files[0], '82b56e484370b5dd99d281a4b91a6f8f4ac7e3e98ce75c15be1f2f23b556d21d'],
+  [files[1], '405d2d9894b6b9f53c6522f675740b32355628b63dc2215dac7729033e8ef242'],
+  [files[2], 'eca88d359a422162f261c449a4c1547d80bdb7029b6111621a82c99e073218c5'],
+])
+
+await assertFresh(target)
+const stage = await mkdtemp(join(tmpdir(), 'nodedc-platform-gelios-provider-v2-'))
+const payload = join(stage, 'payload')
+try {
+  await mkdir(payload, { recursive: true })
+  for (const rel of files) {
+    const source = join(platformRoot, rel.replace(/^platform\//, ''))
+    const stat = await lstat(source)
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`source_boundary_invalid:${rel}`)
+    const bytes = await readFile(source)
+    if (sha(bytes) !== expectedSha256.get(rel)) throw new Error(`source_sha256_mismatch:${rel}`)
+    await mkdir(dirname(join(payload, rel)), { recursive: true })
+    await cp(source, join(payload, rel), { force: false })
+  }
+  await writeFile(join(stage, 'manifest.env'), `id=${id}\ncomponent=platform\ntype=app-overlay\n`, 'utf8')
+  await writeFile(join(stage, 'files.txt'), `${files.join('\n')}\n`, 'utf8')
+  await mkdir(artifactRoot, { recursive: true })
+  run('python3', ['-c', canonicalTarScript(), target, stage])
+  console.log(JSON.stringify({
+    ok: true,
+    id,
+    artifact: target,
+    artifactSha256: sha(await readFile(target)),
+    services: [],
+    providerPackage: 'gelios.provider.v2',
+    authentication: 'SDK query token',
+    runtimeEffect: 'catalog-only; no service restart',
+    files,
+  }, null, 2))
+} finally {
+  await rm(stage, { recursive: true, force: true })
+}
+
+async function assertFresh(path) {
+  try {
+    await lstat(path)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return
+    throw error
+  }
+  throw new Error('artifact_already_exists')
+}
+
+function canonicalTarScript() {
+  return [
+    'import gzip,io,pathlib,sys,tarfile',
+    'root=pathlib.Path(sys.argv[2])',
+    "with open(sys.argv[1],'wb') as out:",
+    " with gzip.GzipFile(filename='',mode='wb',fileobj=out,compresslevel=9,mtime=0) as gz:",
+    "  with tarfile.open(fileobj=gz,mode='w',format=tarfile.PAX_FORMAT) as tar:",
+    "   for top in ('manifest.env','files.txt','payload'):",
+    "    p=root/top; paths=[p]+(sorted(p.rglob('*')) if p.is_dir() else [])",
+    '    for x in paths:',
+    '     info=tar.gettarinfo(str(x),arcname=x.relative_to(root).as_posix())',
+    "     info.uid=info.gid=0; info.uname=info.gname='root'; info.mtime=0; info.mode=0o755 if info.isdir() else 0o644",
+    "     with (open(x,'rb') if info.isfile() else io.BytesIO()) as src: tar.addfile(info,src if info.isfile() else None)",
+  ].join('\n')
+}
+
+function sha(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    maxBuffer: 128 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (result.status !== 0) throw new Error(`${command}_failed:${result.stderr || result.stdout}`)
+  return result
+}

packages/external-provider-contract/providers/gelios/v2/README.md

@@ -0,0 +1,16 @@
+# Gelios provider package v2
+
+Version 2 keeps the provider-neutral `fleet.positions.current.v1` mapping and
+switches the Robot2B connection transport to the durable Gelios SDK token that
+is already used by the legacy Engine/Cesium contour.
+
+- endpoint: `GET https://admin.geliospro.com/sdk/`;
+- static query: `svc=get_units`, `params={}`;
+- secret query parameter: `token`, injected only by native NDC L2
+  `httpQueryAuth` credentials;
+- token lifecycle: one durable access artifact, no refresh operation;
+- graph/package/logs never contain the token value.
+
+The v1 REST bearer package remains immutable historical evidence. A v2
+connection must use a separately registered native Query Auth credential whose
+name is `token`; it must not reinterpret an SDK token as an HTTP Bearer token.

packages/external-provider-contract/providers/gelios/v2/index.mjs

@@ -0,0 +1,11 @@
+export {
+  GELIOS_POSITIONS_DATA_PRODUCT_ID,
+  GELIOS_POSITIONS_DATA_PRODUCT_VERSION,
+  GELIOS_POSITIONS_ONTOLOGY_REVISION,
+  GELIOS_PROVIDER_PACKAGE_ID,
+  GELIOS_PROVIDER_PACKAGE_VERSION,
+  GELIOS_UNIT_SOURCE_ID_PREFIX,
+  geliosProviderPackageV2,
+} from "./package.mjs";
+
+export { geliosUnitsCurrentFixtureV1 as geliosUnitsCurrentFixtureV2 } from "../v1/fixtures/units-current.fixture.mjs";

packages/external-provider-contract/providers/gelios/v2/package.mjs

@@ -0,0 +1,102 @@
+import { geliosProviderPackageV1 } from "../v1/package.mjs";
+
+export const GELIOS_PROVIDER_PACKAGE_ID = "gelios.provider.v2";
+export const GELIOS_PROVIDER_PACKAGE_VERSION = "2.0.0";
+export const GELIOS_POSITIONS_DATA_PRODUCT_ID = "fleet.positions.current.v1";
+export const GELIOS_POSITIONS_DATA_PRODUCT_VERSION = "1.0.0";
+export const GELIOS_POSITIONS_ONTOLOGY_REVISION = "ontology.map.moving_object.v1";
+export const GELIOS_UNIT_SOURCE_ID_PREFIX = "gelios-unit-";
+
+const AUTH_MODE_ID = "gelios.sdk-query-token.v2";
+const CAPABILITY_ID = "gelios.units.current.sdk.read";
+const REALTIME_PROFILE_ID = "gelios.positions.current.realtime.v2";
+const MANUAL_PROFILE_ID = "gelios.positions.current.manual.v2";
+const MAPPING_ID = "gelios.units.to.fleet.positions.current.v2";
+const TEMPLATE_ID = "gelios.positions.current.l2.v2";
+
+const value = structuredClone(geliosProviderPackageV1);
+value.id = GELIOS_PROVIDER_PACKAGE_ID;
+value.version = GELIOS_PROVIDER_PACKAGE_VERSION;
+value.manifest = {
+  ...value.manifest,
+  id: "gelios.provider.manifest.v2",
+  version: GELIOS_PROVIDER_PACKAGE_VERSION,
+  authModeIds: [AUTH_MODE_ID],
+  capabilityIds: [CAPABILITY_ID],
+  collectionProfileIds: [REALTIME_PROFILE_ID, MANUAL_PROFILE_ID],
+  mappingContractIds: [MAPPING_ID],
+  l2TemplateIds: [TEMPLATE_ID],
+};
+value.authModes = [{
+  id: AUTH_MODE_ID,
+  kind: "api_token",
+  credentialOwner: "ndc_l2_credentials",
+  bindingCardinality: "one_per_connection",
+  transport: {
+    placement: "query",
+    name: "token",
+  },
+  tokenLifecycle: {
+    artifacts: ["access"],
+    requestArtifact: "access",
+    refreshMode: "not_applicable",
+  },
+  secretHandling: {
+    store: "ndc_l2_credentials",
+    exposeToGraph: false,
+    persistInPackage: false,
+  },
+}];
+value.capabilities = [{
+  ...value.capabilities[0],
+  id: CAPABILITY_ID,
+  authModeId: AUTH_MODE_ID,
+  request: {
+    method: "GET",
+    baseUrl: "https://admin.geliospro.com",
+    path: "/sdk/",
+    query: {
+      svc: "get_units",
+      params: "{}",
+    },
+    response: value.capabilities[0].request.response,
+  },
+}];
+value.collectionProfiles = value.collectionProfiles.map((profile, index) => ({
+  ...profile,
+  id: index === 0 ? REALTIME_PROFILE_ID : MANUAL_PROFILE_ID,
+  version: GELIOS_PROVIDER_PACKAGE_VERSION,
+  capabilityIds: [CAPABILITY_ID],
+  mappingContractId: MAPPING_ID,
+  l2TemplateId: TEMPLATE_ID,
+}));
+value.mappingContracts = [{
+  ...value.mappingContracts[0],
+  id: MAPPING_ID,
+  version: GELIOS_PROVIDER_PACKAGE_VERSION,
+  sourceCapabilityId: CAPABILITY_ID,
+}];
+value.l2Templates = [{
+  ...value.l2Templates[0],
+  id: TEMPLATE_ID,
+  version: GELIOS_PROVIDER_PACKAGE_VERSION,
+  credentialBindings: value.l2Templates[0].credentialBindings.map((binding) => (
+    binding.role === "provider" ? { ...binding, authModeId: AUTH_MODE_ID } : binding
+  )),
+  steps: value.l2Templates[0].steps.map((step) => {
+    if (step.kind === "provider_request" || step.kind === "extract_items") {
+      return { ...step, capabilityId: CAPABILITY_ID };
+    }
+    if (step.kind === "semantic_mapping") return { ...step, mappingContractId: MAPPING_ID };
+    return step;
+  }),
+}];
+
+export const geliosProviderPackageV2 = deepFreeze(value);
+
+function deepFreeze(input) {
+  if (!input || typeof input !== "object" || Object.isFrozen(input)) return input;
+  Object.freeze(input);
+  for (const child of Object.values(input)) deepFreeze(child);
+  return input;
+}

packages/external-provider-contract/test/provider-package.test.mjs

@@ -14,6 +14,7 @@ import {
   geliosProviderPackageV1,
   geliosUnitsCurrentFixtureV1,
 } from "../providers/gelios/v1/index.mjs";
+import { geliosProviderPackageV2 } from "../providers/gelios/v2/index.mjs";
 import { normalizeDataProductDefinition } from "../../../services/external-data-plane/src/data-product-policy.mjs";
 
 const expectedFields = [
@@ -33,6 +34,23 @@ const expectedFields = [
 ];
 
 assert.deepEqual(validateProviderPackage(geliosProviderPackageV1), { ok: true, errors: [] });
+assert.deepEqual(validateProviderPackage(geliosProviderPackageV2), { ok: true, errors: [] });
+
+const geliosSdkAuth = geliosProviderPackageV2.authModes[0];
+const geliosSdkUnitsRead = geliosProviderPackageV2.capabilities[0];
+assert.equal(geliosProviderPackageV2.id, "gelios.provider.v2");
+assert.equal(geliosProviderPackageV2.version, "2.0.0");
+assert.equal(geliosSdkAuth.id, "gelios.sdk-query-token.v2");
+assert.deepEqual(geliosSdkAuth.transport, { placement: "query", name: "token" });
+assert.deepEqual(geliosSdkAuth.tokenLifecycle, {
+  artifacts: ["access"],
+  requestArtifact: "access",
+  refreshMode: "not_applicable",
+});
+assert.equal(geliosSdkUnitsRead.request.baseUrl, "https://admin.geliospro.com");
+assert.equal(geliosSdkUnitsRead.request.path, "/sdk/");
+assert.deepEqual(geliosSdkUnitsRead.request.query, { svc: "get_units", params: "{}" });
+assert.equal(geliosProviderPackageV2.dataProducts[0].id, GELIOS_POSITIONS_DATA_PRODUCT_ID);
 
 const geliosAuth = geliosProviderPackageV1.authModes[0];
 const geliosUnitsRead = geliosProviderPackageV1.capabilities[0];