@ekanos/harness 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -25,9 +25,10 @@ import { type WidgetRenderState } from '@ekanos/sdk/components';
25
25
  * - ADDED a `WidgetBoundary` around each widget so one partner's crash
26
26
  * renders a readable card instead of blanking the page.
27
27
  *
28
- * Everything else — grid classes, row grouping, the props handed to the
29
- * provider, the two props handed to the widget — is verbatim. If the real grid
30
- * changes, this needs the same change.
28
+ * Everything else — grid classes, the props handed to the provider, the two
29
+ * props handed to the widget — is verbatim. Row grouping is not copied: both
30
+ * grids import it from `@ekanos/sdk/layout` (the design system's widget rules). If
31
+ * the real grid's markup changes, this needs the same change.
31
32
  */
32
33
  type DashboardGridLayout = 'masonry' | 'two-column';
33
34
  interface DashboardGridProps {
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
  import { jsx, jsxs } from "react/jsx-runtime";
3
+ import { buildRowGroups, splitBalanced } from "@ekanos/sdk/layout";
3
4
  import { HarnessWidgetProvider } from "./harness-widget-provider.js";
4
- import { buildRowGroups, splitBalanced } from "./row-groups.js";
5
5
  import { WidgetBoundary } from "./widget-boundary.js";
6
6
  function DashboardGrid({
7
7
  widgets,
@@ -27,6 +27,16 @@ function DashboardGrid({
27
27
  group.widget.id
28
28
  );
29
29
  }
30
+ if (group.type === "compact") {
31
+ return /* @__PURE__ */ jsx(
32
+ "div",
33
+ {
34
+ className: "grid grid-cols-1 items-start gap-5 @xl/dashboard:grid-cols-2 @4xl/dashboard:grid-cols-4",
35
+ children: group.widgets.map((widget) => /* @__PURE__ */ jsx(WidgetRenderer, { widget, ...shared }, widget.id))
36
+ },
37
+ group.widgets[0].id
38
+ );
39
+ }
30
40
  const { left, right } = splitBalanced(group.widgets);
31
41
  return /* @__PURE__ */ jsxs(
32
42
  "div",
@@ -69,13 +69,13 @@ function ActivationPage() {
69
69
  /* @__PURE__ */ jsx(AlertTitle, { children: mode === "live" ? "Submissions run onActivate on the dev server" : "Submissions go nowhere" }),
70
70
  /* @__PURE__ */ jsxs(AlertDescription, { children: [
71
71
  /* @__PURE__ */ jsxs("p", { children: [
72
- "The harness has no Ekanos backend. Submitting shows you the",
72
+ mode === "live" ? "The generated shell stands in for the Ekanos backend. Submitting stores every string field of the form in .ekanos/local-secrets.json and hands it to your live handlers as ctx.secrets, then runs onActivate on that context \u2014 the same rule the host applies to the activation row. " : "The harness has no Ekanos backend. Submitting shows you the ",
73
+ mode === "live" ? null : /* @__PURE__ */ jsx("code", { children: "ActivationResult" }),
74
+ mode === "live" ? "The " : " your form handed back instead of persisting it \u2014 which is the part worth checking, since that payload is what the real activation action would store. The ",
75
+ "dialog, the capability and permission sections and the connected state are the real ones, rendered from your",
73
76
  " ",
74
- /* @__PURE__ */ jsx("code", { children: "ActivationResult" }),
75
- " your form handed back instead of persisting it \u2014 which is the part worth checking, since that payload is what the real activation action would store. The dialog, the capability and permission sections and the connected state are the real ones, rendered from your ",
76
77
  /* @__PURE__ */ jsx("code", { children: "defineIntegration()" }),
77
- " ",
78
- "declaration."
78
+ " declaration."
79
79
  ] }),
80
80
  /* @__PURE__ */ jsx("p", { "data-test": "activation-mode-notice-top", children: mode === "live" ? "Live API: an OAuth form\u2019s Connect runs the real loop through the generated shell (see Local OAuth below), onActivate runs on the server-held context that loop stored tokens in, and widgets reach real vendors through useIntegrationFetch(). The host runs the same declarations, with real enforcement, after you publish." : "Fixtures: an OAuth form reads its connection status from oauth.connected in your harness entry, onActivate runs in this browser against a context seeded from triggerMocks, and nothing leaves your machine." })
81
81
  ] })
@@ -0,0 +1,13 @@
1
+ /**
2
+ * `/<slug>` — the address the home page's cards, the back link and every
3
+ * partner's muscle memory land on. It has no surface of its own: the five
4
+ * surfaces live one segment deeper, so this sends the browser to
5
+ * `/<slug>/widgets` (the one every session starts on) instead of rendering a
6
+ * 404 under a working toolbar, which is how it read for three releases.
7
+ *
8
+ * A client component because the registry — and therefore "does this slug
9
+ * exist" — is only readable from context (see routes.ts). The effect is the
10
+ * redirect itself: `redirect()` from next/navigation is a server-side
11
+ * primitive, and `router.replace` is the client equivalent.
12
+ */
13
+ export declare function IntegrationIndexPage(): null;
@@ -0,0 +1,17 @@
1
+ "use client";
2
+ import { useEffect } from "react";
3
+ import { notFound, useParams, useRouter } from "next/navigation";
4
+ import { useHarnessIntegration } from "../registry-context.js";
5
+ function IntegrationIndexPage() {
6
+ const params = useParams();
7
+ const router = useRouter();
8
+ const integration = useHarnessIntegration();
9
+ useEffect(() => {
10
+ if (integration) router.replace(`/${params.slug}/widgets`);
11
+ }, [integration, params.slug, router]);
12
+ if (!integration) notFound();
13
+ return null;
14
+ }
15
+ export {
16
+ IntegrationIndexPage
17
+ };
@@ -237,8 +237,16 @@ async function oauthCallback(ctx) {
237
237
  const stateParam = params.get("state");
238
238
  const consumed = stateParam ? ctx.state.nonces.consume(stateParam) : { status: "unknown" };
239
239
  const returnPath = consumed.status === "unknown" ? defaultReturnPath(ctx.slug) : consumed.entry.returnPath;
240
- if (params.get("error")) {
241
- return oauthError(ctx, returnPath, "denied");
240
+ const providerError = params.get("error");
241
+ if (providerError) {
242
+ console.error(
243
+ `[harness:${ctx.slug}] oauth/callback: provider returned an error (${providerError.slice(0, 200)}): ${(params.get("error_description") ?? "").slice(0, 500)}`
244
+ );
245
+ return oauthError(
246
+ ctx,
247
+ returnPath,
248
+ providerError === "access_denied" ? "denied" : "provider_error"
249
+ );
242
250
  }
243
251
  if (consumed.status === "unknown")
244
252
  return oauthError(ctx, returnPath, "invalid");
@@ -259,7 +267,7 @@ async function oauthCallback(ctx) {
259
267
  });
260
268
  if (!exchange.ok) {
261
269
  console.error(
262
- `[harness:${ctx.slug}] oauth/callback: code exchange failed (${exchange.reason}${exchange.reason === "http_error" ? ` ${exchange.status}` : ""}${exchange.reason === "fetch_failed" ? `: ${exchange.message}` : ""}).`
270
+ `[harness:${ctx.slug}] oauth/callback: code exchange failed (${exchange.reason}${exchange.reason === "http_error" ? ` ${exchange.status}` : ""}${exchange.reason === "fetch_failed" ? `: ${exchange.message}` : ""}).${exchange.reason === "http_error" && exchange.body ? ` Provider response: ${exchange.body}` : ""}`
263
271
  );
264
272
  return oauthError(ctx, returnPath, "exchange_failed");
265
273
  }
@@ -25,7 +25,9 @@ import type { OAuthProviderDeclaration, OAuthTokens } from '@ekanos/sdk/integrat
25
25
  * Identical to the host's, because `partnerOAuthErrorParam()` in `@ekanos/sdk`
26
26
  * maps exactly these codes to user-facing copy.
27
27
  */
28
- export type PartnerOAuthErrorCode = 'denied' | 'expired' | 'invalid' | 'unauthorized' | 'not_configured' | 'exchange_failed' | 'save_failed';
28
+ export type PartnerOAuthErrorCode = 'denied' | 'expired' | 'invalid' | 'unauthorized' | 'not_configured' | 'exchange_failed' | 'save_failed'
29
+ /** The provider redirected back with an `error` other than `access_denied`. */
30
+ | 'provider_error';
29
31
  /** RFC 7636 code verifier: 32 random bytes, base64url (43 chars). */
30
32
  export declare function generateCodeVerifier(): string;
31
33
  /** RFC 7636 S256 challenge: base64url(sha256(verifier)). */
@@ -73,6 +75,20 @@ export declare function buildAuthorizeUrl(input: BuildAuthorizeUrlInput): string
73
75
  * what `raw` is for.
74
76
  */
75
77
  export declare function parseTokenResponse(payload: unknown, now: Date): OAuthTokens | null;
78
+ /**
79
+ * A provider's error body, safe to log: the client secret, the code and any
80
+ * `access_token` / `refresh_token` value are replaced, then it is truncated.
81
+ * Redaction runs before truncation so a secret cut in half cannot slip past.
82
+ */
83
+ export declare function redactProviderErrorBody(text: string, secrets: readonly string[]): string;
84
+ /** Token-endpoint client authentication: HTTP Basic, or `client_id` / `client_secret` in the body. */
85
+ export declare function applyClientAuthentication(input: {
86
+ method: 'client_secret_basic' | 'client_secret_post' | undefined;
87
+ clientId: string;
88
+ clientSecret: string;
89
+ headers: Record<string, string>;
90
+ body: URLSearchParams;
91
+ }): void;
76
92
  export interface ExchangeAuthorizationCodeInput {
77
93
  ctx: Pick<IntegrationContext, 'fetch'>;
78
94
  provider: OAuthProviderDeclaration;
@@ -88,11 +104,12 @@ export type ExchangeAuthorizationCodeResult = {
88
104
  ok: true;
89
105
  tokens: OAuthTokens;
90
106
  }
91
- /** The endpoint answered non-2xx. `status` is safe to log; the body is not. */
107
+ /** The endpoint answered non-2xx. `body` is redacted and truncated for logging. */
92
108
  | {
93
109
  ok: false;
94
110
  reason: 'http_error';
95
111
  status: number;
112
+ body: string;
96
113
  }
97
114
  /** 2xx, but not JSON or not a token response. */
98
115
  | {
@@ -108,7 +125,8 @@ export type ExchangeAuthorizationCodeResult = {
108
125
  /**
109
126
  * POST the declared `tokenUrl` through **`ctx.fetch`** — so the exchange is
110
127
  * subject to the definition's own egress list exactly as it is on the host.
111
- * Client authentication is HTTP Basic, as on the host. The response body is
112
- * NEVER logged, on any path — it is the credential.
128
+ * Client authentication follows `provider.tokenAuthMethod`, as on the host. A
129
+ * SUCCESS body is NEVER logged — it is the credential. A failure body is
130
+ * logged only after `redactProviderErrorBody`.
113
131
  */
114
132
  export declare function exchangeAuthorizationCode(input: ExchangeAuthorizationCodeInput): Promise<ExchangeAuthorizationCodeResult>;
@@ -81,6 +81,26 @@ function parseTokenResponse(payload, now) {
81
81
  raw: record
82
82
  };
83
83
  }
84
+ const ERROR_BODY_MAX_CHARS = 500;
85
+ function redactProviderErrorBody(text, secrets) {
86
+ let redacted = text.replace(/("(?:access|refresh)_token"\s*:\s*)"[^"]*"/gi, '$1"[redacted]"').replace(/((?:access|refresh)_token=)[^&\s]+/gi, "$1[redacted]");
87
+ for (const secret of secrets) {
88
+ if (secret) redacted = redacted.split(secret).join("[redacted]");
89
+ }
90
+ return redacted.slice(0, ERROR_BODY_MAX_CHARS);
91
+ }
92
+ function applyClientAuthentication(input) {
93
+ if (input.method === "client_secret_post") {
94
+ input.body.set("client_id", input.clientId);
95
+ input.body.set("client_secret", input.clientSecret);
96
+ return;
97
+ }
98
+ const basic = Buffer.from(
99
+ `${input.clientId}:${input.clientSecret}`,
100
+ "utf8"
101
+ ).toString("base64");
102
+ input.headers.Authorization = `Basic ${basic}`;
103
+ }
84
104
  async function exchangeAuthorizationCode(input) {
85
105
  const body = new URLSearchParams({
86
106
  grant_type: "authorization_code",
@@ -90,19 +110,22 @@ async function exchangeAuthorizationCode(input) {
90
110
  if (input.codeVerifier) {
91
111
  body.set("code_verifier", input.codeVerifier);
92
112
  }
93
- const basic = Buffer.from(
94
- `${input.clientId}:${input.clientSecret}`,
95
- "utf8"
96
- ).toString("base64");
113
+ const headers = {
114
+ Accept: "application/json",
115
+ "Content-Type": "application/x-www-form-urlencoded"
116
+ };
117
+ applyClientAuthentication({
118
+ method: input.provider.tokenAuthMethod,
119
+ clientId: input.clientId,
120
+ clientSecret: input.clientSecret,
121
+ headers,
122
+ body
123
+ });
97
124
  let response;
98
125
  try {
99
126
  response = await input.ctx.fetch(input.provider.tokenUrl, {
100
127
  method: "POST",
101
- headers: {
102
- Accept: "application/json",
103
- "Content-Type": "application/x-www-form-urlencoded",
104
- Authorization: `Basic ${basic}`
105
- },
128
+ headers,
106
129
  body: body.toString()
107
130
  });
108
131
  } catch (error) {
@@ -113,7 +136,13 @@ async function exchangeAuthorizationCode(input) {
113
136
  };
114
137
  }
115
138
  if (!response.ok) {
116
- return { ok: false, reason: "http_error", status: response.status };
139
+ const text = await response.text().catch(() => "");
140
+ return {
141
+ ok: false,
142
+ reason: "http_error",
143
+ status: response.status,
144
+ body: redactProviderErrorBody(text, [input.clientSecret, input.code])
145
+ };
117
146
  }
118
147
  let payload;
119
148
  try {
@@ -128,6 +157,7 @@ async function exchangeAuthorizationCode(input) {
128
157
  return { ok: true, tokens };
129
158
  }
130
159
  export {
160
+ applyClientAuthentication,
131
161
  buildAuthorizeUrl,
132
162
  callbackUrl,
133
163
  errorRedirectUrl,
@@ -136,6 +166,7 @@ export {
136
166
  generateCodeVerifier,
137
167
  generateNonce,
138
168
  parseTokenResponse,
169
+ redactProviderErrorBody,
139
170
  safeReturnPath,
140
171
  successRedirectUrl
141
172
  };
package/dist/routes.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * The five `[slug]` surfaces plus their shared layout.
2
+ * The five `[slug]` surfaces, the `/<slug>` index that redirects to the first
3
+ * of them, plus their shared layout.
3
4
  *
4
5
  * Every one is a `'use client'` module: the registry holds live React component
5
6
  * references, which cannot cross the server/client boundary as props, so each
@@ -17,6 +18,7 @@
17
18
  * local dev tool that is not a real cost.
18
19
  */
19
20
  export { IntegrationLayout } from './internal/routes/integration-layout.js';
21
+ export { IntegrationIndexPage } from './internal/routes/integration-index-page.js';
20
22
  export { WidgetsPage } from './internal/routes/widgets-page.js';
21
23
  export { SingleWidgetPage } from './internal/routes/single-widget-page.js';
22
24
  export { TilePage } from './internal/routes/tile-page.js';
package/dist/routes.js CHANGED
@@ -1,5 +1,6 @@
1
1
  "use client";
2
2
  import { IntegrationLayout } from "./internal/routes/integration-layout.js";
3
+ import { IntegrationIndexPage } from "./internal/routes/integration-index-page.js";
3
4
  import { WidgetsPage } from "./internal/routes/widgets-page.js";
4
5
  import { SingleWidgetPage } from "./internal/routes/single-widget-page.js";
5
6
  import { TilePage } from "./internal/routes/tile-page.js";
@@ -7,6 +8,7 @@ import { ActivationPage } from "./internal/routes/activation-page.js";
7
8
  import { TriggersPage } from "./internal/routes/triggers-page.js";
8
9
  export {
9
10
  ActivationPage,
11
+ IntegrationIndexPage,
10
12
  IntegrationLayout,
11
13
  SingleWidgetPage,
12
14
  TilePage,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ekanos/harness",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Ekanos chrome, from fixtures, with no Supabase or auth; and, in live mode, a real localhost OAuth loop over your own dev-app credentials.",
5
5
  "bugs": {
6
6
  "email": "npm@govastly.com"
@@ -63,15 +63,15 @@
63
63
  "tw-animate-css": "1.4.0"
64
64
  },
65
65
  "devDependencies": {
66
- "@ekanos/sdk": "0.5.0",
67
- "@ekanos/ui": "0.5.0",
66
+ "@ekanos/sdk": "0.7.0",
67
+ "@ekanos/ui": "0.7.0",
68
68
  "@kit/tsconfig": "0.1.0",
69
69
  "@tailwindcss/postcss": "4.3.3",
70
70
  "@tanstack/react-query": "5.103.2",
71
71
  "@types/node": "25.0.1",
72
72
  "@types/react": "19.2.18",
73
73
  "@types/react-dom": "19.2.5",
74
- "next": "16.3.6",
74
+ "next": "16.4.0",
75
75
  "next-intl": "^4.14.7",
76
76
  "react": "19.2.8",
77
77
  "react-dom": "19.2.8",
@@ -83,8 +83,8 @@
83
83
  "zod": "4.6.5"
84
84
  },
85
85
  "peerDependencies": {
86
- "@ekanos/sdk": "^0.4.0 || ^0.5.0",
87
- "@ekanos/ui": "^0.4.0 || ^0.5.0",
86
+ "@ekanos/sdk": "^0.7.0",
87
+ "@ekanos/ui": "^0.4.0 || ^0.5.0 || ^0.6.0 || ^0.7.0",
88
88
  "@tanstack/react-query": "^5.101.4",
89
89
  "next": "^16.0.0",
90
90
  "next-intl": "^4.14.7",
@@ -94,7 +94,7 @@
94
94
  "tailwindcss": "^4.0.0"
95
95
  },
96
96
  "ekanos": {
97
- "shellContract": 2
97
+ "shellContract": 3
98
98
  },
99
99
  "scripts": {
100
100
  "build": "tsup && tsc -p tsconfig.build.json && node scripts/rewrite-esm-specifiers.mjs && node scripts/build-css.mjs",
@@ -1,23 +0,0 @@
1
- import { WidgetConfig } from '@ekanos/sdk';
2
- export type RowGroup = {
3
- type: 'full';
4
- widget: WidgetConfig;
5
- } | {
6
- type: 'half';
7
- widgets: WidgetConfig[];
8
- };
9
- /**
10
- * Build row groups that preserve widget order. Contiguous runs of half-width
11
- * widgets are grouped together; full-width widgets each get their own row.
12
- */
13
- export declare function buildRowGroups(widgets: WidgetConfig[]): RowGroup[];
14
- export declare function getColSpan(widget: WidgetConfig): 1 | 2;
15
- /**
16
- * Splits a run of half-width widgets into two balanced columns, alternating
17
- * into whichever column is currently shorter (left wins ties) — preserves
18
- * the exact alternation `MasonryGrid` rendered inline before extraction.
19
- */
20
- export declare function splitBalanced(widgets: WidgetConfig[]): {
21
- left: WidgetConfig[];
22
- right: WidgetConfig[];
23
- };
@@ -1,37 +0,0 @@
1
- function buildRowGroups(widgets) {
2
- const groups = [];
3
- let halfBatch = [];
4
- for (const widget of widgets) {
5
- if (getColSpan(widget) === 2) {
6
- if (halfBatch.length > 0) {
7
- groups.push({ type: "half", widgets: halfBatch });
8
- halfBatch = [];
9
- }
10
- groups.push({ type: "full", widget });
11
- } else {
12
- halfBatch.push(widget);
13
- }
14
- }
15
- if (halfBatch.length > 0) {
16
- groups.push({ type: "half", widgets: halfBatch });
17
- }
18
- return groups;
19
- }
20
- function getColSpan(widget) {
21
- const w = widget.layouts?.lg?.w ?? 6;
22
- return w > 6 ? 2 : 1;
23
- }
24
- function splitBalanced(widgets) {
25
- const left = [];
26
- const right = [];
27
- for (const w of widgets) {
28
- if (left.length <= right.length) left.push(w);
29
- else right.push(w);
30
- }
31
- return { left, right };
32
- }
33
- export {
34
- buildRowGroups,
35
- getColSpan,
36
- splitBalanced
37
- };