Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7162834b43 |
No files matched your search
@@ -36,15 +36,6 @@ Application code is **identical** across editions — always calls `auth()`, `si
|
||||
|
||||
---
|
||||
|
||||
## Decentralized Plugin Authentication (Token Exchange)
|
||||
|
||||
For cross-domain plugin communication (Local App connecting to Marketplace or Data Engines), WWV uses an **Asymmetric JWT Token Exchange (PKCE)** model.
|
||||
- **PKCE Flow**: The Local App uses standard OAuth 2.0 PKCE to exchange a `code` for a long-lived API key from the Marketplace.
|
||||
- **Token Exchange**: The Local App exchanges its long-lived API key for a short-lived, audience-bound JWT before connecting to a decentralized Data Engine.
|
||||
- **WebSocket First-Message Auth**: Data Engines enforce a "First-Message Auth" pattern over WebSockets. The client MUST immediately send a `{ type: "auth", v: 1, token: "..." }` message upon opening the connection to prevent SSRF vulnerabilities and credential leakage.
|
||||
|
||||
---
|
||||
|
||||
## Registration & Auto-Provisioning
|
||||
|
||||
Registration: `app.worldwideview.dev/register`
|
||||
|
||||
@@ -36,7 +36,6 @@ Frontend runs at `http://localhost:3000`.
|
||||
- **Framework**: Vitest with jsdom environment
|
||||
- **Coverage**: `src/lib/**`, `src/core/**`, `src/plugins/**`
|
||||
- **Run**: `pnpm test` (or `vitest run`)
|
||||
- **Type-Level Contract Testing**: When defining shared TypeScript interfaces/contracts (e.g., in `wwv-plugin-sdk`), you MUST use `expectTypeOf` from `vitest` to assert the actual contract shapes at compile-time instead of writing literal-value identity runtime assertions. You must also enforce `@ts-expect-error` negative type tests to ensure missing or invalid fields trigger compilation errors.
|
||||
- **Key test files**: `rateLimit.test.ts`, `edition.test.ts`, `demoAdmin.test.ts`, `DeclarativePlugin.test.ts`, `cors.test.ts`, `repository.test.ts`, `marketplaceToken.test.ts`
|
||||
|
||||
## Security Headers
|
||||
|
||||
@@ -191,12 +191,6 @@ Plugins declare auth type in the manifest:
|
||||
|
||||
**Recommended for scale:** `token-exchange` — your server is never in the hot path for data requests.
|
||||
|
||||
### Shared Auth Contracts & Security Branding
|
||||
|
||||
When implementing the `token-exchange` flow or communicating across domains, all plugins and endpoints MUST use the strictly defined shared auth contracts from `@worldwideview/wwv-plugin-sdk/src/auth-contracts.ts` (e.g., `TokenExchangeRequest`, `WebSocketAuthMessage`).
|
||||
|
||||
**Sensitive Credentials**: All long-lived secrets (like API keys and tokens) MUST use the `SensitiveString` branded type and be instantiated via the `sensitive(str)` factory function. This prevents accidental logging/serialization and creates a single grep target for security audits.
|
||||
|
||||
---
|
||||
|
||||
## Plugin Development Workflows
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@worldwideview/wwv-plugin-sdk",
|
||||
"version": "1.6.0",
|
||||
"version": "1.5.1",
|
||||
"description": "Plugin SDK — types, interfaces, and utilities for building WorldWideView globe plugins",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
|
||||
@@ -1,92 +0,0 @@
|
||||
import { describe, it, expectTypeOf } from "vitest";
|
||||
import type {
|
||||
TokenExchangeRequest,
|
||||
TokenExchangeResponse,
|
||||
WebSocketAuthMessage,
|
||||
SensitiveString,
|
||||
Tier,
|
||||
PKCEConnectRequest,
|
||||
PKCETokenExchange,
|
||||
PKCETokenExchangeResponse,
|
||||
PluginJwtClaims,
|
||||
AuthErrorResponse,
|
||||
JWK,
|
||||
JWKSResponse,
|
||||
WebSocketMessage
|
||||
} from "./auth-contracts";
|
||||
|
||||
describe("Auth Contracts", () => {
|
||||
it("TokenExchangeRequest has exact required properties", () => {
|
||||
expectTypeOf<TokenExchangeRequest>().toHaveProperty("apiKey").toEqualTypeOf<SensitiveString>();
|
||||
expectTypeOf<TokenExchangeRequest>().toHaveProperty("audience").toEqualTypeOf<string>();
|
||||
|
||||
// @ts-expect-error - missing required apiKey
|
||||
const badReq: TokenExchangeRequest = { audience: "engine-123" };
|
||||
});
|
||||
|
||||
it("TokenExchangeResponse has exact required properties", () => {
|
||||
expectTypeOf<TokenExchangeResponse>().toHaveProperty("token").toEqualTypeOf<SensitiveString>();
|
||||
expectTypeOf<TokenExchangeResponse>().toHaveProperty("expiresAt").toEqualTypeOf<number>();
|
||||
expectTypeOf<TokenExchangeResponse>().toHaveProperty("kid").toEqualTypeOf<string>();
|
||||
expectTypeOf<TokenExchangeResponse>().toHaveProperty("tier").toEqualTypeOf<Tier | undefined>();
|
||||
|
||||
// @ts-expect-error - missing required token
|
||||
const badRes: TokenExchangeResponse = { expiresAt: 123456789, kid: "key-1" };
|
||||
});
|
||||
|
||||
it("WebSocketAuthMessage has exact required properties including protocol version", () => {
|
||||
expectTypeOf<WebSocketAuthMessage>().toHaveProperty("type").toEqualTypeOf<"auth">();
|
||||
expectTypeOf<WebSocketAuthMessage>().toHaveProperty("v").toEqualTypeOf<1>();
|
||||
expectTypeOf<WebSocketAuthMessage>().toHaveProperty("token").toEqualTypeOf<SensitiveString>();
|
||||
|
||||
// @ts-expect-error - missing version
|
||||
const badMsg: WebSocketAuthMessage = { type: "auth", token: "jwt-token-here" as SensitiveString };
|
||||
|
||||
// @ts-expect-error - wrong version
|
||||
const badVersion: WebSocketAuthMessage = { type: "auth", v: 2, token: "jwt-token-here" as SensitiveString };
|
||||
});
|
||||
|
||||
it("WebSocketMessage is a discriminated union correctly containing WebSocketAuthMessage", () => {
|
||||
expectTypeOf<WebSocketMessage>().extract<{ type: "auth" }>().toEqualTypeOf<WebSocketAuthMessage>();
|
||||
});
|
||||
|
||||
it("PKCEConnectRequest has correct snake_case shape", () => {
|
||||
expectTypeOf<PKCEConnectRequest>().toHaveProperty("state").toEqualTypeOf<string>();
|
||||
expectTypeOf<PKCEConnectRequest>().toHaveProperty("code_challenge").toEqualTypeOf<string>();
|
||||
expectTypeOf<PKCEConnectRequest>().toHaveProperty("code_challenge_method").toEqualTypeOf<"S256">();
|
||||
});
|
||||
|
||||
it("PKCETokenExchange implements RFC 7636 fields", () => {
|
||||
expectTypeOf<PKCETokenExchange>().toHaveProperty("grant_type").toEqualTypeOf<"authorization_code">();
|
||||
expectTypeOf<PKCETokenExchange>().toHaveProperty("redirect_uri").toEqualTypeOf<string>();
|
||||
expectTypeOf<PKCETokenExchange>().toHaveProperty("client_id").toEqualTypeOf<string>();
|
||||
expectTypeOf<PKCETokenExchange>().toHaveProperty("code").toEqualTypeOf<string>();
|
||||
expectTypeOf<PKCETokenExchange>().toHaveProperty("code_verifier").toEqualTypeOf<string>();
|
||||
});
|
||||
|
||||
it("PKCETokenExchangeResponse has exact required properties", () => {
|
||||
expectTypeOf<PKCETokenExchangeResponse>().toHaveProperty("apiKey").toEqualTypeOf<SensitiveString>();
|
||||
expectTypeOf<PKCETokenExchangeResponse>().toHaveProperty("tier").toEqualTypeOf<Tier | undefined>();
|
||||
expectTypeOf<PKCETokenExchangeResponse>().toHaveProperty("issuedAt").toEqualTypeOf<number | undefined>();
|
||||
});
|
||||
|
||||
it("PluginJwtClaims structure matches requirements", () => {
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("iss").toEqualTypeOf<string>();
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("aud").toEqualTypeOf<string>();
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("exp").toEqualTypeOf<number>();
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("jti").toEqualTypeOf<string>();
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("tier").toEqualTypeOf<Tier>();
|
||||
expectTypeOf<PluginJwtClaims>().toHaveProperty("plugins").toEqualTypeOf<string[] | undefined>();
|
||||
});
|
||||
|
||||
it("JWKSResponse conforms to RFC 7517", () => {
|
||||
expectTypeOf<JWKSResponse>().toHaveProperty("keys").toEqualTypeOf<JWK[]>();
|
||||
expectTypeOf<JWK>().toHaveProperty("kty").toEqualTypeOf<string>();
|
||||
expectTypeOf<JWK>().toHaveProperty("kid").toEqualTypeOf<string>();
|
||||
});
|
||||
|
||||
it("AuthErrorResponse has basic OAuth error fields", () => {
|
||||
expectTypeOf<AuthErrorResponse>().toHaveProperty("error").toEqualTypeOf<string>();
|
||||
expectTypeOf<AuthErrorResponse>().toHaveProperty("error_description").toEqualTypeOf<string>();
|
||||
});
|
||||
});
|
||||
@@ -1,168 +0,0 @@
|
||||
/**
|
||||
* @file auth-contracts.ts
|
||||
* @description Shared contracts for Decentralized Plugin Authentication.
|
||||
*/
|
||||
|
||||
/**
|
||||
* A branded string type for sensitive credentials to prevent accidental logging or serialization.
|
||||
*/
|
||||
export type SensitiveString = string & { readonly __brand: "SensitiveString" };
|
||||
|
||||
/**
|
||||
* Factory function to safely cast a string to a SensitiveString.
|
||||
* This provides a single grep target for every place a secret enters the system.
|
||||
*/
|
||||
export const sensitive = (s: string): SensitiveString => s as SensitiveString;
|
||||
|
||||
/**
|
||||
* The authorization tier of the plugin client.
|
||||
*/
|
||||
export type Tier = "basic" | "pro";
|
||||
|
||||
/**
|
||||
* Payload sent by the Local App to the Marketplace to exchange a long-lived
|
||||
* API key for a short-lived, audience-bound JWT.
|
||||
*
|
||||
* @see ADR-001 §2 "Asymmetric JWT Token Exchange"
|
||||
*/
|
||||
export interface TokenExchangeRequest {
|
||||
/**
|
||||
* The long-lived API key securely stored by the Local App
|
||||
* @security Sensitive credential — must not be logged.
|
||||
*/
|
||||
apiKey: SensitiveString;
|
||||
/** The specific Data Engine (audience) the Local App wants to connect to */
|
||||
audience: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Payload returned by the Marketplace after a successful token exchange.
|
||||
*
|
||||
* @see ADR-001 §2 "Asymmetric JWT Token Exchange"
|
||||
*/
|
||||
export interface TokenExchangeResponse {
|
||||
/** The JWT to attach to the WebSocket auth message */
|
||||
token: SensitiveString;
|
||||
/** Unix timestamp (ms) indicating when the token expires — so the Local App can refresh pre-emptively */
|
||||
expiresAt: number;
|
||||
/** Key id used to sign — useful when JWKS has multiple keys during rotation */
|
||||
kid: string;
|
||||
/** The entitlement tier of the client */
|
||||
tier?: Tier;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scaffold for a discriminated union of all possible WebSocket messages.
|
||||
*/
|
||||
export type WebSocketMessage = WebSocketAuthMessage; // | WebSocketSubscribeMessage | ...
|
||||
|
||||
/**
|
||||
* First message sent by the Local App over the WebSocket to authenticate with the Data Engine.
|
||||
*
|
||||
* @see ADR-001 §4 "WebSocket Authentication Gating"
|
||||
*/
|
||||
export interface WebSocketAuthMessage {
|
||||
type: "auth";
|
||||
/** Protocol version to allow future wire shape evolution */
|
||||
v: 1;
|
||||
/** The short-lived JWT obtained from the Token Exchange */
|
||||
token: SensitiveString;
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard PKCE request shape during the initial connect flow.
|
||||
* Note: snake_case fields below match RFC 7636 / RFC 6749 wire format.
|
||||
*/
|
||||
export interface PKCEConnectRequest {
|
||||
/** Randomly generated state to prevent CSRF */
|
||||
state: string;
|
||||
/** The S256 hash of the code verifier */
|
||||
code_challenge: string;
|
||||
/** The challenge method (always "S256" for our implementation) */
|
||||
code_challenge_method: "S256";
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard PKCE exchange payload.
|
||||
* Implements strict PKCE-protected Authorization Code Grant per RFC 7636.
|
||||
* Note: snake_case fields below match RFC 7636 / RFC 6749 wire format.
|
||||
*/
|
||||
export interface PKCETokenExchange {
|
||||
grant_type: "authorization_code";
|
||||
redirect_uri: string;
|
||||
client_id: string;
|
||||
/** The authorization code received from the callback */
|
||||
code: string;
|
||||
/** The original unhashed verifier to prove possession */
|
||||
code_verifier: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Payload returned by the Marketplace after a successful PKCE token exchange.
|
||||
*/
|
||||
export interface PKCETokenExchangeResponse {
|
||||
/** The long-lived API key issued to the Local App */
|
||||
apiKey: SensitiveString;
|
||||
/** Tier surfaced so the Local App can show "Connected to X tier" in the UI */
|
||||
tier?: Tier;
|
||||
/** Optional issuance timestamp for future rotation/expiration logic */
|
||||
issuedAt?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* The expected structure of the JWT claims after signature verification.
|
||||
*/
|
||||
export interface PluginJwtClaims {
|
||||
/** Issuer (Marketplace URL) */
|
||||
iss: string;
|
||||
/** Subject (The plugin identifier or tenant ID) */
|
||||
sub: string;
|
||||
/** Audience (The specific Data Engine URL or ID) */
|
||||
aud: string;
|
||||
/** Expiration Time (Unix seconds) */
|
||||
exp: number;
|
||||
/** Not Before (Unix seconds) */
|
||||
nbf: number;
|
||||
/** Issued At (Unix seconds) */
|
||||
iat: number;
|
||||
/** JWT ID (Unique identifier for the token to prevent replay) */
|
||||
jti: string;
|
||||
/** The entitlement tier */
|
||||
tier: Tier;
|
||||
/**
|
||||
* Optional array of allowed plugin namespace prefixes.
|
||||
* @example ["wwv-plugin-aviation", "wwv-plugin-maritime-*"]
|
||||
*/
|
||||
plugins?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard error response shape for the auth API.
|
||||
*/
|
||||
export interface AuthErrorResponse {
|
||||
/** Short error code (e.g., "invalid_grant", "rate_limit_exceeded") */
|
||||
error: string;
|
||||
/** Human-readable error description */
|
||||
error_description: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* JSON Web Key representing a single public key used to verify signatures.
|
||||
* Mirrors the RFC 7517 shape.
|
||||
*/
|
||||
export interface JWK {
|
||||
kty: string;
|
||||
kid: string;
|
||||
use?: string;
|
||||
alg?: string;
|
||||
n?: string;
|
||||
e?: string;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Expected shape of the /.well-known/jwks.json endpoint.
|
||||
*/
|
||||
export interface JWKSResponse {
|
||||
keys: JWK[];
|
||||
}
|
||||
@@ -299,6 +299,3 @@ export type DataBusEvents = {
|
||||
};
|
||||
|
||||
export * from "./viteGlobals";
|
||||
|
||||
// ─── Auth Contracts ──────────────────────────────────────────
|
||||
export * from "./auth-contracts";
|
||||
Reference in new issue
Block a user