Files
SilvertakanaandClaude Opus 4.7 26568429bc feat(auth): ADR-001 Workstream C — ticket auth, SSRF protection, and pre-flight audit (#171)
* feat(auth): implement ADR-001 Workstream C — ticket auth, SSRF, and pre-flight audit

C1: Boot-time ENCRYPTION_MASTER_KEY / AUTH_SECRET validation (instrumentation.ts);
    remove silent fallback in encryption.ts; guard marketplace token from data-plane misuse.
C2: SSRF host-allowlist (PROXY_HOST_ALLOWLIST) in ssrf.ts; route iframe proxy through safeFetch.
C3: ticketClient.ts — exchanges long-lived API key for 5-min EdDSA ticket from Marketplace;
    audience fixed to ENGINE_AUDIENCE='wwv-data-engine'; cache keyed by engine not plugin.
C4: WsClient.ts first-message auth — sends {type:'auth',v:1,token} on open; queues subscribes
    until {type:'welcome'}; gated by ticketAuthEnabledForPlugin.
C5: edition.ts — ticketAuthEnabledForPlugin reads NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS flag.
Step 0: docs/deploys/2026-05-21-adr-001-preflight.md + docs/feature-flags.md audit artifacts.
Tests: ticketClient.spec, WsClient.spec, ssrf.spec updated (342 passing).

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): resolve three PR #171 type-check and startup failures

- auth-contracts.spec.ts: assert WebSocketAuthMessage.token as PluginTicket
  (not SensitiveString — distinct branded types fail toEqualTypeOf equality)
- pkce.spec.ts: replace function(){return this} mock with arrow fn to fix
  TS2683 implicit-this error in strict mode
- test-local-dev.yml: add ENCRYPTION_MASTER_KEY so instrumentation.ts boot
  validation doesn't crash the startup test in CI

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): fix pkce mock constructor and env injection for startup test

- pkce.spec.ts: use function(this: object) instead of arrow fn so the
  mock can be called with `new Configuration(...)` (arrow functions are
  not constructors)
- test-local-dev.yml: sed-replace ENCRYPTION_MASTER_KEY in .env after
  cp .env.example so Next.js instrumentation boot check passes in CI

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): also sed-replace AUTH_SECRET in .env for startup test

.env.example has AUTH_SECRET= (empty), which Next.js loads and overrides
the system env var, causing the same boot crash as ENCRYPTION_MASTER_KEY.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(setup): auto-generate ENCRYPTION_MASTER_KEY in setup.mjs

The Playwright CI workflow uses `pnpm run setup` which previously only
generated AUTH_SECRET. ENCRYPTION_MASTER_KEY remained empty from
.env.example, causing instrumentation.ts boot validation to crash.

This fix also improves the new-developer onboarding experience — both
required secrets are now generated in a single setup step.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 <[email protected]>
2026-05-21 17:00:24 +12:00
..

@worldwideview/wwv-plugin-sdk

Plugin SDK for building WorldWideView globe plugins. Provides TypeScript types, interfaces, and utilities that all plugins depend on.

Installation

npm install @worldwideview/wwv-plugin-sdk

Core Interfaces

Interface Purpose
WorldPlugin Main plugin contract — lifecycle, data fetching, rendering
GeoEntity A positioned object on the globe (lat/lon/alt + properties)
PluginContext Host app context injected into every plugin at init
LayerConfig Visual layer settings (color, clustering, limits)
CesiumEntityOptions Per-entity Cesium rendering options (point, model, etc.)
SelectionBehavior Optional trail / fly-to behavior on entity selection
FilterDefinition Declarative filter UI (text, select, range, boolean)
ServerPluginConfig Server-side API routing and polling config

Quick Example

import type { WorldPlugin, GeoEntity, TimeRange, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";

export class MyPlugin implements WorldPlugin {
  id = "my-plugin";
  name = "My Plugin";
  description = "A custom WorldWideView plugin";
  icon = "🌍";
  category = "custom";
  version = "1.0.0";

  async initialize(ctx: PluginContext) { /* setup */ }
  destroy() { /* cleanup */ }

  async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
    // Return geo-positioned entities
    return [];
  }

  getPollingInterval() { return 30000; }
  getLayerConfig(): LayerConfig {
    return { color: "#3b82f6", clusterEnabled: true, clusterDistance: 40 };
  }
  renderEntity(entity: GeoEntity): CesiumEntityOptions {
    return { type: "point", color: "#3b82f6", size: 6 };
  }
}

Changelog

  • v1.0.3 — Added README with core interfaces and usage docs.
  • v1.0.2 — Package metadata updates.
  • v1.0.1 — Package configuration fixes.
  • v1.0.0 — Initial release with core types and interfaces.

License

ISC