@bardioc/app-sdk 0.4.10 → 0.4.11

package/dist/dev-proxy.js

@@ -1,5 +1,7 @@
 import { createServer } from 'node:http';
 import { resolveDevAuthEnv } from './dev-auth-env.js';
+// BFF mount of the dynamic relay to published REST backends.
+const RELAY_PATH_PREFIX = '/relay';
 export async function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -95,9 +97,12 @@ export function createDevAuthProxyHandler(options) {
         }
         addDevSecretHeader(req, headers, devSecret);
         dropOriginKeepReferer(headers);
-        // Dev auth is dev-secret only: never forward X-App-Id, so the BFF app-token
-        // exchange (which would also demand X-Scope-ID) can never be triggered here.
-        headers.delete('X-App-Id');
+        // Dev auth is dev-secret only, so X-App-Id is dropped and the BFF app-token exchange
+        // (which would also demand X-Scope-ID) is never triggered. The relay is the exception:
+        // it authorizes on the exchanged app identity and answers 403 without one.
+        if (!upstreamPath.startsWith(`${RELAY_PATH_PREFIX}/`)) {
+            headers.delete('X-App-Id');
+        }
         // BFF rejects /bardioc/ calls without this CSRF marker header; stamp it like the host does.
         headers.set('X-Requested-With', 'XMLHttpRequest');
         let body;

package/dist/dev.d.ts

@@ -1,6 +1,12 @@
 export interface DevBridgeOptions {
     /** Base URL prepended to SDK transport paths. Defaults to `/rest`. */
     apiBaseUrl?: string;
+    /**
+     * The app's ogit/Auth/Application id, sent as X-App-ID on scoped calls like the host
+     * does. Needed for `transport.backend(...)`: the relay authorizes on the exchanged app
+     * identity and refuses calls without it.
+     */
+    appId?: string;
     debug?: boolean;
 }
 export declare function isInsideIframe(): boolean;

package/dist/dev.js

@@ -12,6 +12,7 @@ export function isDevStandalone() {
 }
 export function installDevBridge(options = {}) {
     const apiBaseUrl = getBaseUrl(options.apiBaseUrl);
+    const appId = options.appId?.trim() || undefined;
     const debug = options.debug ?? false;
     const origin = window.location.origin;
     const log = (...args) => {
@@ -49,6 +50,11 @@ export function installDevBridge(options = {}) {
         }
         if (resolvedScopeId) {
             headers.set('X-Scope-ID', resolvedScopeId);
+            // The BFF app-token exchange rejects X-App-ID without X-Scope-ID, so a scopeless
+            // call goes out as the user, exactly as the host sends it.
+            if (appId) {
+                headers.set('X-App-ID', appId);
+            }
         }
         const url = `${apiBaseUrl}${payload.path}`;
         log('[transport]', payload.method ?? 'GET', url);

package/dist/host-bridge.js

@@ -1,4 +1,5 @@
 import { SDK_MSG } from './protocol.js';
+import { BackendTransport } from './transports/backend-transport.js';
 import { GraphTransport } from './transports/graph-transport.js';
 import { OsTransport } from './transports/os-transport.js';
 let counter = 0;
@@ -176,6 +177,7 @@ export function createHostBridge(config) {
     const transport = {
         graph: new GraphTransport(baseRequest, { debug }),
         os: new OsTransport(baseRequest),
+        backend: routeKey => new BackendTransport(baseRequest, routeKey),
     };
     function idb(storeName) {
         const normalizedStoreName = assertStoreName(storeName);

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contr
 export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
 export type { SdkMessageType } from './protocol.js';
 export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';
-export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';
+export type { Application, BackendRequestOptions, BackendTransport, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/transports/backend-transport.d.ts

@@ -0,0 +1,24 @@
+import type { BackendRequestOptions, SdkTransportPayload } from '../types.js';
+export declare function isRouteKey(routeKey: string): boolean;
+/**
+ * Client for an application's own REST backend, reached through the BFF relay at
+ * `/relay/{routeKey}`. The host stamps the calling app id and scope; the BFF checks the
+ * app against the route's whitelist and forwards the request with an app-scoped token.
+ */
+export declare class BackendTransport {
+    private _request;
+    private readonly routeKey;
+    constructor(_request: <T = unknown>(payload: SdkTransportPayload) => Promise<T>, routeKey: string);
+    /**
+     * Send a request to the backend. `path` is what the backend sees, after the relay
+     * stripped `/relay/{routeKey}`. Scope is required unless stated otherwise: the relay
+     * refuses an app-scoped call without one.
+     *
+     * @throws {EntityNotFoundError} on 404 errors
+     * @throws {ValidationError} on 400 errors
+     * @throws {PermissionError} on 403 errors (app not whitelisted for the route)
+     * @throws {NetworkError} on HTTP errors, including 502 when the backend is unreachable
+     * @throws {TimeoutError} on request timeout
+     */
+    request<T = unknown>(options: BackendRequestOptions): Promise<T>;
+}

package/dist/transports/backend-transport.js

@@ -0,0 +1,54 @@
+import { ValidationError } from '../errors.js';
+import { parseOsError } from './os-transport.js';
+const RELAY_BASE = '/relay';
+// Mirrors the BFF's route key rule: one path segment, "." and ".." excluded.
+const ROUTE_KEY_PATTERN = /^[A-Za-z0-9._-]+$/;
+export function isRouteKey(routeKey) {
+    return routeKey !== '.' && routeKey !== '..' && ROUTE_KEY_PATTERN.test(routeKey);
+}
+/**
+ * Client for an application's own REST backend, reached through the BFF relay at
+ * `/relay/{routeKey}`. The host stamps the calling app id and scope; the BFF checks the
+ * app against the route's whitelist and forwards the request with an app-scoped token.
+ */
+export class BackendTransport {
+    _request;
+    routeKey;
+    constructor(_request, routeKey) {
+        this._request = _request;
+        this.routeKey = routeKey;
+        if (!isRouteKey(routeKey)) {
+            throw new ValidationError(`Invalid relay route key: "${routeKey}"`, 'routeKey');
+        }
+    }
+    /**
+     * Send a request to the backend. `path` is what the backend sees, after the relay
+     * stripped `/relay/{routeKey}`. Scope is required unless stated otherwise: the relay
+     * refuses an app-scoped call without one.
+     *
+     * @throws {EntityNotFoundError} on 404 errors
+     * @throws {ValidationError} on 400 errors
+     * @throws {PermissionError} on 403 errors (app not whitelisted for the route)
+     * @throws {NetworkError} on HTTP errors, including 502 when the backend is unreachable
+     * @throws {TimeoutError} on request timeout
+     */
+    async request(options) {
+        const path = options.path.startsWith('/') ? options.path : `/${options.path}`;
+        try {
+            return await this._request({
+                path: `${RELAY_BASE}/${this.routeKey}${path}`,
+                method: options.method || 'GET',
+                body: options.body,
+                contentType: options.contentType,
+                scopeId: options.scopeId,
+                scopePolicy: options.scopePolicy ?? 'required',
+            });
+        }
+        catch (error) {
+            throw parseOsError(error, `backend.${this.routeKey}.request`, {
+                path: options.path,
+                method: options.method,
+            });
+        }
+    }
+}

package/dist/transports/os-transport.d.ts

@@ -1,4 +1,5 @@
 import type { Application, Configuration, CreateMemberInput, CreateUnitInput, FileEntry, InstanceList, OrgMember, OrgStructure, OrgUnit, OsRequestOptions, SdkTransportPayload, UpdateMemberInput, UpdateUnitInput, UserProfile } from '../types.js';
+export declare function parseOsError(error: any, operation: string, context?: Record<string, unknown>): Error;
 /** OS transport class providing OS/system operations */
 export declare class OsTransport {
     private readonly _request;

package/dist/transports/os-transport.js

@@ -1,7 +1,7 @@
 import { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from '../errors.js';
 const OS_BASE = '/os';
 // Maps backend errors to typed SDK errors
-function parseOsError(error, operation, context) {
+export function parseOsError(error, operation, context) {
     let statusCode;
     let errorMessage = error.message || 'Unknown error';
     if (error.responsePayload && typeof error.responsePayload === 'object') {

package/dist/types.d.ts

@@ -202,6 +202,7 @@ export interface SdkIdbStore {
 export interface SdkTransport {
     graph: GraphTransport;
     os: OsTransport;
+    backend(routeKey: string): BackendTransport;
 }
 /** Graph node in raw backend format (ogit/* fields) */
 export interface GraphNodeRaw {
@@ -363,6 +364,7 @@ export interface OsRequestOptions extends TransportScopeOptions {
     contentType?: string;
     scopePolicy?: 'none' | 'optional' | 'required';
 }
+export type BackendRequestOptions = OsRequestOptions;
 /** Live connection between an iframe app and its host OS. */
 export interface HostBridge {
     /** Perform the SDK handshake. Resolves with host context. Cached after first call. */
@@ -392,3 +394,4 @@ export interface HostBridge {
 /** Forward declarations for transport classes */
 export type GraphTransport = import('./transports/graph-transport.js').GraphTransport;
 export type OsTransport = import('./transports/os-transport.js').OsTransport;
+export type BackendTransport = import('./transports/backend-transport.js').BackendTransport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bardioc/app-sdk",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "SDK for building apps for the Bardioc OS",
   "license": "MIT",
   "private": false,