Skip to content

Edge services — design note

Status: In Review Owners: Nadim Rafehi Reviewers: <PASETO reviewer>, platform leads Decision date: (fill when accepted)

Scope: The concrete shape of an edge service — an installed, addressable external service that Sky Ledge apps, widgets, and event actions call through a secured platform proxy. The “resource” concept from web-component-apps-and-resources.md, made concrete. Companion: web-component-apps-and-resources.md (the two-pillar architecture this sits in).

The PASETO section (§7) is a proposal + open questions for a reviewer with deeper PASETO depth; the rest is agreed shape from design review.


0. Why we’re doing this

The platform is increasingly asked for domain-specific data and behaviour — a TPMS dashboard, a fuel report, an “Investigate” / “Request footage” action on an event. The wrong way to ship these is to push domain models, heavy analytics, secrets, and outbound calls into the core or the browser. Edge services are the one secured boundary that lets domain data and domain actions live outside the core while the platform stays the single, permissioned front door.

This is not just for apps. The same edge-service + proxy is the mechanism behind every place a domain needs data or an action:

  • Apps / dashboards — a TPMS or fuel dashboard pulling quarter-wide aggregations from a domain service instead of hammering the general API.
  • Event actions — an event drawer’s Investigate, Request footage, Reconcile fuel invoking a domain service (the EDGE_SERVICE action target in the event display/actions model).
  • Event-drawer & asset-drawer widgets — a config-driven widget fetching domain data (a footage panel, a maintenance summary) via skyledge.edgeService(...).
  • Reports — bespoke, pre-computed domain reporting served from a service’s own store.

The motivation in one line: give domain data and actions a secure home at the edge, reached only through the platform, so we stop encoding domain logic — and secrets, and heavy lifting — into the front-end or the core. Concretely it removes three problems we have today:

  • No identity reaches a plugin. The SDK passes no token, so a widget can’t securely call an external service on the user’s behalf. The proxy + minted token fixes that.
  • The general API is built for real-time / single-asset. It’s inefficient for, say, a quarter of fleet TPMS aggregation; a service with its own optimised store serves that instead.
  • Front-end-driven calls are insecure and heavy. Keys in the browser, business logic in the client. The proxy makes the platform the front door: no keys in the browser, and every call arrives at the service carrying a verifiable, minted identity to authorize against.

And it keeps the core domain-agnostic: a new vertical is edge services + configuration, not core changes — “a platform, not a product.”


1. What it is (and the name)

An edge service is a service that lives outside the Sky Ledge core, owns a domain’s data and/or actions, and is reached only through the platform. It’s the day-one “edge service” idea made a first-class, secured, installable capability.

On the name: we deliberately did not call it Service or Resource — both collide heavily in the backend (*-service is the app-layer module convention across 12 modules; FormResource/FileResource/… are pervasive). EdgeService is our ubiquitous language, is architecturally precise (“a service at the edge”), and reinforces core-vs-edge. App-layer classes are named by action (EdgeServiceInstaller, EdgeServiceProvisioner), never EdgeServiceService.

  • SDK: skyledge.edgeService(id)
  • Action target: { type: 'EDGE_SERVICE', … }

2. Decisions locked

# Decision
D1 Flat, single concept (EdgeService), addressed by a client-facing identifier (the internal PK is a UUID id). Endpoints are not modelled — opaque HTTP.
D2 The backend holds one record type: a per-org installation. The portal owns the catalog, the app→edge-service dependency map, and install orchestration. The core never learns about a global catalog or which app needs what.
D3 Java backend is the proxy. On each call it resolves the install, mints a short-lived PASETO, and forwards to the service’s base URL.
D4 Standardize on the minted PASETO (no per-service secret vault). Third-party services that can’t validate it are fronted by a thin Sky Ledge adapter.
D5 Opaque HTTP pass-through via a reserved segment: ANY /edge-services/{identifier}/invoke/{*path}.
D6 Installed = callable; the edge service authorizes (v1). No requiredPermission gate on the install — any user in the org can invoke an enabled service, and the edge service decides authorization from the token identity (permissions are often richer than a single grant). The token stays minimal identity; services query the platform for the user’s roles/details if they need them.
D7 Platform is agnostic to how a service sources its data (own pipeline / batch-from-API / thin proxy).

3. The backend record — EdgeService installation (per org)

EdgeService (installation)
id // internal UUID (primary key)
identifier // unique client-facing string ref (e.g. "tpms") — used by invoke, apps, actions
organizationId
name // display
description // display
baseUrl // where the proxy forwards (https://…) — input-only, never returned
audience // the `aud` claim minted into the PASETO — input-only, never returned
enabled // on/off without deleting
config? // optional passthrough bag (headers, timeouts) — input-only, never returned
  • Scope: one record per {organizationId, identifier} (identifier unique per org; id is the internal UUID). A shared multi-tenant service is one install per org pointing at the same baseUrl (the PASETO’s org claim tells the service which tenant). A per-org deployment simply has a different baseUrl per org’s install.
  • The proxy reads only this record. It’s the source of truth for routing (baseUrl) and token audience (audience). There’s no permission gate in v1 — an enabled install is callable by any user in the org; the edge service authorizes.
  • Reads: redacted for users, full for the org owner. List and get are readable by any user in the org, returning a redacted view (id, identifier, name, description, enabled) so a client can check whether a service is installed and enabled. The org owner additionally receives baseUrl, audience and config — for audit and correction — and these are never returned to non-owners. Writes (install / update / uninstall) require org-admin. The proxy must not echo baseUrl in error responses or headers.
  • Storage: MongoDB, event/infra Mongo db, schema-tolerant. No change to any existing aggregate.

4. Backend ↔ portal split

Concern Where Why
The invoke proxy Backend Must resolve baseUrl/audience per call.
Installation records Backend The proxy’s source of truth.
Admin CRUD for installs Backend (§8) The portal calls it to provision.
The catalog of available edge services (the “menu”) Portal Not a core concern.
The app → edge-service dependency map Portal “The TPMS app needs the TPMS service” is orchestration, not core.
The check that an org has required services installed, and provisioning them Portal Calls the backend admin API to create installs.
Catalog versioning, health/status views Portal Backend install only has enabled.

The core stays domain-agnostic: it holds the per-org installs it needs to do its one job (proxy + mint), nothing more.


5. The proxy — routing & flow

Route: ANY /edge-services/{identifier}/invoke/{*path} — opaque pass-through of method, path, query, body; response streamed back. The /invoke/ segment separates the forwarded path from the platform’s own routes.

Client (app / widget / action, Auth0 cookie/bearer)
→ ANY /edge-services/{identifier}/invoke/{*path}?{query}
→ Java backend proxy:
1. resolve {identifier} within the caller's org → EdgeService install (404 if none, 403 if !enabled)
2. mint PASETO { sub(effective), org, cr?, aud:install.audience, src?, exp≈60s }
3. forward method + /{path}?{query} + body → install.baseUrl + /{path}
with header Authorization: Bearer <paseto> (or a dedicated header)
4. stream the service's response (status, headers, body) back to the client
# no permission gate — the edge service authorizes from the token identity
  • Effective identity: sub is the post-impersonation user (resolve through SupportSessionAwareAuthProvider, not raw JWT claims), so support sessions don’t leak the operator’s identity to edge services.
  • Reuses existing seams: AuthProvider.getMachineToMachineToken is the natural place to mint (today it just re-forwards the Auth0 JWT); SessionTokenRelayFilter is prior art for “produce a bearer for a downstream hop”; the CloudFront report signer is prior art for “platform mints short-lived scoped access to an external thing.”

SDK / action mapping:

  • skyledge.edgeService('tpms').get('/summary?period=quarter') → GET /edge-services/tpms/invoke/summary?period=quarter
  • { type:'EDGE_SERVICE', ref:'tpms', method:'POST', path:'/request', body:{…} } → POST /edge-services/tpms/invoke/request

6. Identity & user details

The token is least-privilege: it proves who (opaque sub) and the org / control-room context — nothing more. Authorization is the edge service’s job (v1 has no platform permission gate): it decides what the user may do, and an edge service that needs email/name/role/permissions queries the platform for them.

  • That lookup cannot use the invoke PASETO (its aud is the edge service, not the platform). The service resolves sub via a platform user-info lookup authenticated as a service consumer (the existing inbound API-key / M2M auth).
  • Deferred: the exact user-info endpoint + how a service authenticates to it — design when the first service needs it.

7. PASETO — proposal + open questions for review

This section is for a reviewer with deeper PASETO depth. Recommendations are a starting proposal; the six questions are the real decisions.

7.1 Proposal

  • Version/purpose: v4.public (Ed25519, asymmetric). Platform signs with the private key; edge services verify with the public key. No shared secret, verify-only for services, public key freely distributable — falls straight out of “standardize on the token, no vault.” (v4.local is symmetric and would reintroduce per-service shared secrets.)
  • Claims: registered iss, sub, aud, exp, iat, jti + custom org, cr?, src?. exp ≈ 60s, minted per call. (No perm claim in v1 — the edge service authorizes.)
  • Validation at the edge: aud == the service’s own audience (stops a token minted for service A being replayed to B), and exp.
  • Key distribution: a discovery endpoint GET /.well-known/edge-keys serving the public key as PASERK (k4.public), so services fetch rather than hard-code.
  • Rotation: a key id in the footer (PASERK kid); the discovery endpoint lists currently-valid keys; platform signs with the newest; services accept any listed key during an overlap window.
  • Replay: jti present but not tracked server-side (60s + aud makes the window tiny) — unless a service needs exactly-once.

7.2 Token shape (proposed)

v4.public payload:
iss: "https://api.skyledge.com"
sub: "<effective user id>"
aud: "<install.audience>"
org: "<organizationId>"
cr: "<controlRoomId>" // optional
src: "<originating app/widget/action>" // optional, debugging/tracing
iat, exp (≈+60s), jti
footer:
kid: "<PASERK key id>" // for rotation

7.3 Open questions for review

  1. PASETO vs JWT/JOSE. PASETO is safer-by-construction (no alg confusion); JWT+JWKS has far broader library support across whatever languages edge services are written in. If services will be polyglot/third-party, is JWT the pragmatic call despite the footguns?
  2. v4.public confirmation. Any reason to prefer v4.local (our claims aren’t secret, so hiding them isn’t a driver)?
  3. Key distribution & rotation. PASERK via a discovery endpoint vs. static per-service config; is footer-kid + overlap-window the rotation model you want?
  4. Implicit assertions. Should we bind the edge-service identity via a PASETO implicit assertion (authenticated, not in the payload) in addition to / instead of aud?
  5. Replay. jti-present-but-untracked acceptable, or do we want built-in replay protection (a jti store)?
  6. Java library. Preferred/vetted lib (jpaseto, paseto4j, …) and its maintenance status?

8. Backend API

Org-scoped. Reads (list/get) are open to any user in the org (redacted); writes are org-admin. The portal uses the writes to provision installs.

# reads — any user (redacted); the org owner also gets baseUrl/audience/config (audit)
GET /edge-services // list installs for the org
GET /edge-services/{id} // read one install (by UUID)
# writes — org-admin · body carries identifier + baseUrl/audience/config
POST /edge-services // install
PUT /edge-services/{id} // update (baseUrl, audience, enabled, config…)
DELETE /edge-services/{id} // uninstall
# proxy — addressed by identifier
ANY /edge-services/{identifier}/invoke/{*path} // (any user in the org; the service authorizes)
GET /.well-known/edge-keys // PASERK public keys (public)
  • Reads: any authenticated user in the org → redacted (used to check installed/enabled); the org owner → full record incl baseUrl/audience/config (for audit/correction). Mirrors the platform’s minRole-gated field pattern.
  • Writes: @PreAuthorize org-admin permission (mirror the asset-type-settings admin-write pattern).
  • Invoke: no platform permission gate in v1 — an enabled install is callable by users in the org; the edge service authorizes.

9. What needs to change (net-new)

Backend

  • EdgeService domain model (§3) + repository + Mongo collection.
  • Admin controllers (§8) — CRUD, org-admin auth.
  • The invoke proxy — a controller/filter that resolves the install, mints the PASETO, and forwards (streaming). Outbound HTTP client (there’s only Auth0-JWKS outbound today, so this is genuinely new).
  • PASETO minting — Ed25519 keypair, signing, the /.well-known/edge-keys PASERK endpoint, rotation. Swap into the getMachineToMachineToken seam.
  • Effective-identity resolution through SupportSessionAwareAuthProvider.

Frontend

  • SDK skyledge.edgeService(id) client (mini-axios over the invoke route) added to the plugin SDK surface.
  • EDGE_SERVICE action target in the event-action dispatcher (folds into the event display/actions model).

Portal (separate)

  • Catalog of edge services, app→edge-service dependency map, install-check + provisioning against the admin API.

Reuse / prior art: AppInstance install lifecycle, SessionTokenRelayFilter (downstream bearer), SupportSessionAwareAuthProvider (effective identity), CloudFront signer (scoped external access).


10. Open / deferred

  • PASETO specifics — §7.3 (for review).
  • Permission gating — v1 has none (the edge service authorizes). If we later want the proxy to *pre-*gate, we can reintroduce a policy on the install (a permission, a set, or an expression) and add a perm/scopes claim — deliberately deferred because real permission needs are often richer than a single grant.
  • User-info / permissions lookup — the endpoint + how a service authenticates to it (§6).
  • Portal catalog/dependency/provisioning design (separate workstream).
  • Health/status surfacing (portal).
  • Rate limiting / quotas per edge service — not in v1; note as a likely follow-up on the proxy.
  • Audit — invoke calls are a natural audit point (who invoked what, src); decide logging depth.

11. Why this is the platform thesis

Domain data and actions live in edge services outside the core; the platform is the secured front door and the only path to them. A new vertical adds edge services + config, not core changes. The core never learns the domain — it just proxies, mints, and permissions. “A platform, not a product,” as concrete capability.