@nsp-labs/agnostic-sdk 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -9,6 +9,24 @@ and pass the runtime OpenAPI schema check.
 
 ## Unreleased
 
+## 1.1.0 - 2026-07-26
+
+### Added
+
+- Added an exact public-surface drift guard and a deterministic manifest
+  fingerprint so Agent codegen can re-read the installed SDK contract on every
+  generation step instead of relying on a copied namespace list.
+- Added `auth.getSession()` for optional App Auth sessions and
+  `auth.requireScopes()` for application-level scope guardrails after session
+  verification.
+
+### Changed
+
+- Runtime SDK manifest consumers can now derive scaffold versions, Agent review
+  allowlists, and source-write deny rules from the exported package contract.
+  The runtime OpenAPI schema is unchanged; the callable SDK surface adds only
+  the backwards-compatible App Auth helpers listed above.
+
 ## 1.0.4 - 2026-06-18
 
 ### Changed

package/README.md

@@ -46,13 +46,33 @@ the incoming App Auth session through the runtime helper:
 ```ts
 const session = await agnostic.auth.requireSession(request);
 
-await agnostic.data.table('orders').records.update(
-  'order_123',
-  { values: { status: 'fulfilled' } },
-  { actor: session.actor },
-);
+await agnostic.data
+  .table('orders')
+  .records.update(
+    'order_123',
+    { values: { status: 'fulfilled' } },
+    { actor: session.actor },
+  );
+```
+
+Use `getSession(request)` for routes that support both guests and signed-in
+users. It returns `null` when the request has no App Auth session:
+
+```ts
+const session = await agnostic.auth.getSession(request);
 ```
 
+Use `requireScopes(request, scopes)` for application-level scope guardrails.
+This verifies the session first and throws `app_auth_scope_missing` when one of
+the required app-user scopes is absent:
+
+```ts
+const session = await agnostic.auth.requireScopes(request, ['orders:write']);
+```
+
+Scope checks do not replace ownership or other business rules in the
+application backend.
+
 The helper extracts `Authorization: Bearer <app-session>` or an
 `agnostic_app_session_*` cookie, then calls
 `/api/v1/runtime/app-auth/session/verify` with the server-side runtime token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsp-labs/agnostic-sdk",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Server-side Runtime SDK for Agnostic project services, workers, automations, and trusted local scripts.",
   "license": "ISC",
   "type": "commonjs",

package/src/index.d.ts

@@ -1,4 +1,5 @@
 export { AgnosticRuntime, RuntimeAppAuthNamespace, RuntimeContextNamespace, RuntimeDataNamespace, RuntimeDataRecordsClient, RuntimeDataTableClient, RuntimeDataViewClient, RuntimeDataViewTableClient, RuntimeWorkflowRunsNamespace, RuntimeWorkflowsNamespace, createAgnosticRuntime, } from './lib/runtime-client';
 export { normalizeApiUrl, resolveRuntimeContext } from './lib/context';
 export { AgnosticRuntimeError } from './lib/errors';
+export { AGNOSTIC_RUNTIME_SDK_MANIFEST, type AgnosticRuntimeSdkManifest, } from './lib/manifest';
 export type { AgnosticRuntimeConfig, ResolvedRuntimeContext, RuntimeActorMetadata, RuntimeActorType, RuntimeAppAuthActor, RuntimeAppAuthCachePolicy, RuntimeAppAuthRequestLike, RuntimeAppAuthSession, RuntimeAppAuthSessionClaims, RuntimeAppAuthUserClaims, RuntimeAppAuthUserResult, RuntimeCreateRecordInput, RuntimeDataField, RuntimeDataViewState, RuntimeIdentityContext, RuntimeListRecordsOptions, RuntimeListWindowOptions, RuntimeRecord, RuntimeRecordMutation, RuntimeRecordsList, RuntimeRequestOptions, RuntimeRowData, RuntimeRowValue, RuntimeTableWindow, RuntimeUpdateRecordInput, RuntimeWorkflowRun, RuntimeWorkflowStepRun, RuntimeWorkflowWaitOptions, WorkflowRunStatus, } from './lib/types';

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgnosticRuntimeError = exports.resolveRuntimeContext = exports.normalizeApiUrl = exports.createAgnosticRuntime = exports.RuntimeWorkflowsNamespace = exports.RuntimeWorkflowRunsNamespace = exports.RuntimeDataViewTableClient = exports.RuntimeDataViewClient = exports.RuntimeDataTableClient = exports.RuntimeDataRecordsClient = exports.RuntimeDataNamespace = exports.RuntimeContextNamespace = exports.RuntimeAppAuthNamespace = exports.AgnosticRuntime = void 0;
+exports.AGNOSTIC_RUNTIME_SDK_MANIFEST = exports.AgnosticRuntimeError = exports.resolveRuntimeContext = exports.normalizeApiUrl = exports.createAgnosticRuntime = exports.RuntimeWorkflowsNamespace = exports.RuntimeWorkflowRunsNamespace = exports.RuntimeDataViewTableClient = exports.RuntimeDataViewClient = exports.RuntimeDataTableClient = exports.RuntimeDataRecordsClient = exports.RuntimeDataNamespace = exports.RuntimeContextNamespace = exports.RuntimeAppAuthNamespace = exports.AgnosticRuntime = void 0;
 var runtime_client_1 = require("./lib/runtime-client");
 Object.defineProperty(exports, "AgnosticRuntime", { enumerable: true, get: function () { return runtime_client_1.AgnosticRuntime; } });
 Object.defineProperty(exports, "RuntimeAppAuthNamespace", { enumerable: true, get: function () { return runtime_client_1.RuntimeAppAuthNamespace; } });
@@ -18,4 +18,6 @@ Object.defineProperty(exports, "normalizeApiUrl", { enumerable: true, get: funct
 Object.defineProperty(exports, "resolveRuntimeContext", { enumerable: true, get: function () { return context_1.resolveRuntimeContext; } });
 var errors_1 = require("./lib/errors");
 Object.defineProperty(exports, "AgnosticRuntimeError", { enumerable: true, get: function () { return errors_1.AgnosticRuntimeError; } });
+var manifest_1 = require("./lib/manifest");
+Object.defineProperty(exports, "AGNOSTIC_RUNTIME_SDK_MANIFEST", { enumerable: true, get: function () { return manifest_1.AGNOSTIC_RUNTIME_SDK_MANIFEST; } });
 //# sourceMappingURL=index.js.map

package/src/lib/manifest.d.ts

@@ -0,0 +1,39 @@
+export declare const AGNOSTIC_RUNTIME_SDK_MANIFEST: Readonly<{
+    readonly promptSync: Readonly<{
+        source: "sdk_exported_manifest";
+        strategy: "inject_on_every_agent_codegen_context";
+        surfaceFingerprint: string;
+        driftPolicy: "fail_ci_on_public_surface_or_package_version_mismatch";
+        memorizedSdkKnowledgeAllowed: false;
+    }>;
+    readonly schema: "agnostic_runtime_sdk_manifest.v1";
+    readonly package: Readonly<{
+        name: "@nsp-labs/agnostic-sdk";
+        version: "1.1.0";
+        factory: "createAgnosticRuntime";
+        runtime: "server_only";
+    }>;
+    readonly context: Readonly<{
+        automatic: true;
+        environmentVariables: readonly string[];
+        secretEnvironmentVariables: readonly string[];
+    }>;
+    readonly rootMembers: readonly [...("data" | "auth" | "context" | "workflows" | "workflowRuns")[], "getRuntimeContext"];
+    readonly clientMethods: readonly ["getRuntimeContext"];
+    readonly namespaces: Readonly<{
+        auth: readonly ("requireSession" | "getSession" | "requireScopes" | "getUser")[];
+        context: readonly "get"[];
+        data: readonly ("table(name).records.delete" | "table(name).records.list" | "table(name).records.create" | "table(name).records.update" | "view(id).table.window")[];
+        workflows: readonly ("start" | "getRun")[];
+        workflowRuns: readonly ("get" | "wait" | "listSteps")[];
+    }>;
+    readonly unsupportedNamespaces: readonly string[];
+    readonly boundaries: Readonly<{
+        controlPlaneProvisioning: "agent_product_tools";
+        runtimeAccess: "server_sdk";
+        browserAccess: "public_api_or_app_auth_session";
+        browserPackageImportAllowed: false;
+        browserRuntimeTokenAllowed: false;
+    }>;
+}>;
+export type AgnosticRuntimeSdkManifest = typeof AGNOSTIC_RUNTIME_SDK_MANIFEST;

package/src/lib/manifest.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGNOSTIC_RUNTIME_SDK_MANIFEST = void 0;
+const node_crypto_1 = require("node:crypto");
+const AUTH_KEYS_LITERAL = [
+    'requireSession',
+    'getSession',
+    'requireScopes',
+    'getUser',
+];
+const AUTH_KEYS = AUTH_KEYS_LITERAL;
+const CONTEXT_KEYS_LITERAL = ['get'];
+const CONTEXT_KEYS = CONTEXT_KEYS_LITERAL;
+const DATA_NAMESPACE_KEYS_LITERAL = ['table', 'view'];
+const DATA_NAMESPACE_KEYS = DATA_NAMESPACE_KEYS_LITERAL;
+const DATA_TABLE_KEYS_LITERAL = ['records'];
+const DATA_TABLE_KEYS = DATA_TABLE_KEYS_LITERAL;
+const DATA_RECORD_KEYS_LITERAL = [
+    'list',
+    'create',
+    'update',
+    'delete',
+];
+const DATA_RECORD_KEYS = DATA_RECORD_KEYS_LITERAL;
+const DATA_VIEW_KEYS_LITERAL = ['table'];
+const DATA_VIEW_KEYS = DATA_VIEW_KEYS_LITERAL;
+const DATA_VIEW_TABLE_KEYS_LITERAL = ['window'];
+const DATA_VIEW_TABLE_KEYS = DATA_VIEW_TABLE_KEYS_LITERAL;
+const WORKFLOW_KEYS_LITERAL = ['start', 'getRun'];
+const WORKFLOW_KEYS = WORKFLOW_KEYS_LITERAL;
+const WORKFLOW_RUN_KEYS_LITERAL = ['get', 'wait', 'listSteps'];
+const WORKFLOW_RUN_KEYS = WORKFLOW_RUN_KEYS_LITERAL;
+const CLIENT_METHODS = Object.freeze(['getRuntimeContext']);
+const NAMESPACES = Object.freeze({
+    auth: Object.freeze([...AUTH_KEYS]),
+    context: Object.freeze([...CONTEXT_KEYS]),
+    data: Object.freeze([
+        ...DATA_RECORD_KEYS.map((method) => `${DATA_NAMESPACE_KEYS[0]}(name).${DATA_TABLE_KEYS[0]}.${method}`),
+        ...DATA_VIEW_TABLE_KEYS.map((method) => `${DATA_NAMESPACE_KEYS[1]}(id).${DATA_VIEW_KEYS[0]}.${method}`),
+    ]),
+    workflows: Object.freeze([...WORKFLOW_KEYS]),
+    workflowRuns: Object.freeze([...WORKFLOW_RUN_KEYS]),
+});
+const ROOT_MEMBERS_LITERAL = Object.freeze([
+    ...Object.keys(NAMESPACES),
+    ...CLIENT_METHODS,
+]);
+const ROOT_MEMBERS = ROOT_MEMBERS_LITERAL;
+const MANIFEST_CONTRACT = Object.freeze({
+    schema: 'agnostic_runtime_sdk_manifest.v1',
+    package: Object.freeze({
+        name: '@nsp-labs/agnostic-sdk',
+        version: '1.1.0',
+        factory: 'createAgnosticRuntime',
+        runtime: 'server_only',
+    }),
+    context: Object.freeze({
+        automatic: true,
+        environmentVariables: Object.freeze([
+            'AGNOSTIC_API_URL',
+            'AGNOSTIC_PROJECT_ID',
+            'AGNOSTIC_ENVIRONMENT',
+            'AGNOSTIC_RUNTIME_TOKEN',
+        ]),
+        secretEnvironmentVariables: Object.freeze(['AGNOSTIC_RUNTIME_TOKEN']),
+    }),
+    rootMembers: ROOT_MEMBERS,
+    clientMethods: CLIENT_METHODS,
+    namespaces: NAMESPACES,
+    unsupportedNamespaces: Object.freeze([
+        'ai',
+        'events',
+        'gateway',
+        'jobs',
+        'realtime',
+        'storage',
+    ]),
+    boundaries: Object.freeze({
+        controlPlaneProvisioning: 'agent_product_tools',
+        runtimeAccess: 'server_sdk',
+        browserAccess: 'public_api_or_app_auth_session',
+        browserPackageImportAllowed: false,
+        browserRuntimeTokenAllowed: false,
+    }),
+});
+const surfaceFingerprint = `sha256:${(0, node_crypto_1.createHash)('sha256')
+    .update(JSON.stringify(MANIFEST_CONTRACT))
+    .digest('hex')}`;
+exports.AGNOSTIC_RUNTIME_SDK_MANIFEST = Object.freeze({
+    ...MANIFEST_CONTRACT,
+    promptSync: Object.freeze({
+        source: 'sdk_exported_manifest',
+        strategy: 'inject_on_every_agent_codegen_context',
+        surfaceFingerprint,
+        driftPolicy: 'fail_ci_on_public_surface_or_package_version_mismatch',
+        memorizedSdkKnowledgeAllowed: false,
+    }),
+});
+//# sourceMappingURL=manifest.js.map

package/src/lib/runtime-client.d.ts

@@ -15,6 +15,8 @@ export declare class RuntimeAppAuthNamespace {
     private readonly openapi;
     constructor(openapi: RuntimeOpenApiClient);
     requireSession(request: RuntimeAppAuthRequestLike | string, options?: RuntimeRequestOptions): Promise<RuntimeAppAuthSession>;
+    getSession(request: RuntimeAppAuthRequestLike | string, options?: RuntimeRequestOptions): Promise<RuntimeAppAuthSession | null>;
+    requireScopes(request: RuntimeAppAuthRequestLike | string, scopes: readonly string[], options?: RuntimeRequestOptions): Promise<RuntimeAppAuthSession>;
     getUser(userId: string, options?: RuntimeRequestOptions): Promise<RuntimeAppAuthUserResult>;
 }
 export declare function createAgnosticRuntime(config?: AgnosticRuntimeConfig): AgnosticRuntime;

package/src/lib/runtime-client.js

@@ -58,11 +58,35 @@ class RuntimeAppAuthNamespace {
                 },
             });
         }
-        const result = await this.openapi.POST(APP_AUTH_VERIFY_SESSION_PATH, {
-            body: { sessionToken },
-            headers: (0, http_client_1.runtimeRequestHeaders)(options),
-        });
-        return (0, http_client_1.unwrapRuntimeResult)(result, 'Failed to verify App Auth session');
+        return verifyAppAuthSession(this.openapi, sessionToken, options);
+    }
+    async getSession(request, options) {
+        const sessionToken = typeof request === 'string'
+            ? normalizeSessionToken(request)
+            : extractAppSessionToken(request);
+        if (!sessionToken) {
+            return null;
+        }
+        return verifyAppAuthSession(this.openapi, sessionToken, options);
+    }
+    async requireScopes(request, scopes, options) {
+        const session = await this.requireSession(request, options);
+        const requiredScopes = Array.from(new Set(scopes.map((scope) => scope.trim()).filter(Boolean)));
+        const availableScopes = new Set(session.user.scopes);
+        const missingScopes = requiredScopes.filter((scope) => !availableScopes.has(scope));
+        if (missingScopes.length > 0) {
+            throw new errors_1.AgnosticRuntimeError({
+                status: 403,
+                code: 'app_auth_scope_missing',
+                message: 'App user is missing a required scope',
+                details: {
+                    availableScopes: session.user.scopes,
+                    missingScopes,
+                    requiredScopes,
+                },
+            });
+        }
+        return session;
     }
     async getUser(userId, options) {
         const result = await this.openapi.GET(APP_AUTH_USER_PATH, {
@@ -78,6 +102,13 @@ exports.RuntimeAppAuthNamespace = RuntimeAppAuthNamespace;
 function createAgnosticRuntime(config = {}) {
     return new AgnosticRuntime(config);
 }
+async function verifyAppAuthSession(openapi, sessionToken, options) {
+    const result = await openapi.POST(APP_AUTH_VERIFY_SESSION_PATH, {
+        body: { sessionToken },
+        headers: (0, http_client_1.runtimeRequestHeaders)(options),
+    });
+    return (0, http_client_1.unwrapRuntimeResult)(result, 'Failed to verify App Auth session');
+}
 class RuntimeContextNamespace {
     constructor(openapi) {
         this.openapi = openapi;