@tealbrick/portal 0.3.0-rc.4 → 0.3.0-rc.5

package/dist/runtime.d.ts

@@ -34,6 +34,13 @@ export interface RuntimeOptions extends RuntimeIdentity {
     fetch?: typeof fetch;
     keys?: JWTVerifyGetKey;
     now?: () => number;
+    /**
+     * Portal-provisioned Knowledge (no local binding for its bindingRef) is reached with a short-lived,
+     * instance-bound grant that Portal mints from the saved canvas wire and Knowledge validates live.
+     * Default true. A local binding whose credentialRef is TEALBRICK_PORTAL_GRANT uses a grant with
+     * its own endpoint. A present-but-mismatched local binding never falls back to a grant.
+     */
+    portalGrants?: boolean;
     audit?: (event: {
         connectionId: string;
         registrationId: string;
@@ -51,6 +58,8 @@ export declare class RuntimeConnector {
     private readonly issuer;
     private readonly fetcher;
     private readonly keys;
+    /** Grant-mode apps whose Portal grant carried an endpoint (Portal-provisioned and reachable). */
+    private readonly reachableByGrant;
     private cached?;
     private refreshing?;
     constructor(options: RuntimeOptions);
@@ -58,6 +67,10 @@ export declare class RuntimeConnector {
     private portal;
     private refresh;
     private matchBinding;
+    /** Grant mode: no local binding at all for this app (Portal-provisioned), or an explicit grant binding. */
+    private grantMode;
+    private grantKey;
+    private portalGrant;
     private current;
     capabilities(force?: boolean): Promise<{
         revision: string;

package/dist/runtime.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
 import { nativeMemoryOperations, nativeRequiredActions, nativeRequest } from './knowledge-native.js';
 const actions = { list_collections: 'read', create_collection: 'create', create_document: 'create', get_document: 'read', update_document: 'update', delete_document: 'delete', search: 'read', memory_recall: 'read', memory_context: 'read', memory_entities: 'read' };
@@ -44,12 +45,19 @@ function validateApps(value) {
     }
     return value;
 }
+const PORTAL_GRANT_REF = 'TEALBRICK_PORTAL_GRANT';
+const GRANT_PATTERN = /^tbkg_[A-Za-z0-9_-]{43}$/;
+// Shared across connector instances in this process: native serve builds a fresh connector per
+// invocation, and a grant is only a bearer that Knowledge re-validates live against Portal.
+const sharedGrants = new Map();
 /** Customer-owned execution boundary. Portal receives configuration acknowledgments only. */
 export class RuntimeConnector {
     options;
     issuer;
     fetcher;
     keys;
+    /** Grant-mode apps whose Portal grant carried an endpoint (Portal-provisioned and reachable). */
+    reachableByGrant = new Set();
     cached;
     refreshing;
     constructor(options) {
@@ -88,7 +96,15 @@ export class RuntimeConnector {
                 throw Error('runtime_invalid_config');
             const apps = validateApps(payload.apps);
             this.cached = { apps, revision: payload.revision, expires: payload.exp * 1000, checked: this.now() };
-            const missing = apps.some(a => !this.matchBinding(a));
+            // A grant-mode app without a local binding is effective only if Portal hands back an endpoint.
+            this.reachableByGrant.clear();
+            for (const a of apps)
+                if (!this.options.bindings[a.bindingRef] && this.grantMode(a)) {
+                    const g = await this.portalGrant(a).catch(() => undefined);
+                    if (g?.endpoint)
+                        this.reachableByGrant.add(a.registrationId);
+                }
+            const missing = apps.some(a => !this.matchBinding(a) && !(this.grantMode(a) && (this.options.bindings[a.bindingRef] || this.reachableByGrant.has(a.registrationId))));
             // An acknowledgement failure must not extend or replace the signed authorization lease.
             await this.portal('/api/runtime/ack', { revision: payload.revision, status: missing ? 'unavailable' : 'effective', ...(missing ? { errorCode: 'binding_missing' } : {}) }).catch(() => undefined);
         }
@@ -98,6 +114,40 @@ export class RuntimeConnector {
         }
     }
     matchBinding(app) { const b = this.options.bindings[app.bindingRef]; return b && b.instanceId === app.instanceId && b.companyId === app.companyId ? b : undefined; }
+    /** Grant mode: no local binding at all for this app (Portal-provisioned), or an explicit grant binding. */
+    grantMode(app) {
+        if (this.options.portalGrants === false)
+            return false;
+        const b = this.options.bindings[app.bindingRef];
+        return !b || (b.credentialRef === PORTAL_GRANT_REF && !!this.matchBinding(app));
+    }
+    // Keyed by the runtime credential too: a rotated credential retires every grant minted under it.
+    async grantKey(app) { const credential = createHash('sha256').update(String(await this.options.credential())).digest('hex').slice(0, 32); return JSON.stringify([this.issuer, this.options.org, this.options.connectionId, credential, app.registrationId, app.instanceId, app.companyId]); }
+    async portalGrant(app) {
+        const key = await this.grantKey(app), cached = sharedGrants.get(key);
+        if (cached && cached.expires - 60000 > this.now())
+            return cached;
+        let response;
+        try {
+            response = await this.portal('/api/runtime/knowledge-grants', { registrationId: app.registrationId });
+        }
+        catch {
+            throw Error('runtime_portal_unavailable');
+        }
+        if (!response.ok)
+            throw Error(response.status === 403 ? 'runtime_action_denied' : response.status === 401 ? 'runtime_config_unavailable' : 'runtime_grant_unavailable');
+        const r = await boundedJson(response, 16384).catch(() => { throw Error('runtime_grant_invalid'); });
+        if (!r || typeof r.grant !== 'string' || !GRANT_PATTERN.test(r.grant) || r.registrationId !== app.registrationId || r.instanceId !== app.instanceId || r.companyId !== app.companyId || typeof r.expiresAt !== 'number' || !Number.isFinite(r.expiresAt) || r.expiresAt <= this.now() || (r.endpoint !== null && r.endpoint !== undefined && !text(r.endpoint)))
+            throw Error('runtime_grant_invalid');
+        const grant = { grant: r.grant, endpoint: r.endpoint ? endpoint(r.endpoint) : null, expires: r.expiresAt };
+        if (sharedGrants.size >= 256)
+            for (const [k, v] of sharedGrants)
+                if (v.expires <= this.now())
+                    sharedGrants.delete(k);
+        if (sharedGrants.size < 256)
+            sharedGrants.set(key, grant);
+        return grant;
+    }
     async current(force = false) {
         if (force || !this.cached || this.now() - this.cached.checked >= 30000) {
             this.refreshing ??= this.refresh().finally(() => { this.refreshing = undefined; });
@@ -113,7 +163,7 @@ export class RuntimeConnector {
             throw Error('runtime_authorization_expired');
         return this.cached;
     }
-    async capabilities(force = false) { const c = await this.current(force); return { revision: c.revision, expiresAt: c.expires, apps: c.apps.map(a => ({ registrationId: a.registrationId, appId: a.appId, actions: [...a.actions], available: !!this.matchBinding(a), operations: allOperations.filter(op => requiredActions(op).every(action => a.actions.includes(action))) })) }; }
+    async capabilities(force = false) { const c = await this.current(force); return { revision: c.revision, expiresAt: c.expires, apps: c.apps.map(a => ({ registrationId: a.registrationId, appId: a.appId, actions: [...a.actions], available: !!this.matchBinding(a) || (this.grantMode(a) && (!!this.options.bindings[a.bindingRef] || this.reachableByGrant.has(a.registrationId))), operations: allOperations.filter(op => requiredActions(op).every(action => a.actions.includes(action))) })) }; }
     async call(registrationId, operation, input = {}, signal) {
         let revision;
         let outcome = 'denied';
@@ -123,8 +173,8 @@ export class RuntimeConnector {
             const app = c.apps.find(a => a.registrationId === registrationId);
             if (!app || !allOperations.includes(operation) || !requiredActions(operation).every(action => app.actions.includes(action)))
                 throw Error('runtime_action_denied');
-            const b = this.matchBinding(app);
-            if (!b)
+            const b = this.matchBinding(app), viaGrant = this.grantMode(app);
+            if (!b && !viaGrant)
                 throw Error('runtime_binding_missing');
             let path, method = 'GET', body, idempotencyKey;
             const company = component(app.companyId);
@@ -241,7 +291,11 @@ export class RuntimeConnector {
             if (path.startsWith('/api/knowledge/'))
                 path += `?companyId=${company}`;
             // Recheck after asynchronous credential resolution; no call may start with an expired lease.
-            const token = await this.options.resolveCredential(b.credentialRef);
+            const grant = viaGrant ? await this.portalGrant(app) : undefined;
+            const target = grant ? (b?.endpoint ?? grant.endpoint) : b.endpoint;
+            if (!target)
+                throw Error('runtime_binding_missing');
+            const token = grant ? grant.grant : await this.options.resolveCredential(b.credentialRef);
             if (!text(token) || /[\r\n]/.test(token))
                 throw Error('runtime_credential_unavailable');
             if (!this.cached || this.cached.revision !== c.revision)
@@ -250,7 +304,10 @@ export class RuntimeConnector {
                 throw Error('runtime_authorization_expired');
             outcome = 'failed';
             const deadline = AbortSignal.timeout(operation.startsWith('memory_native_') ? 610000 : operation.startsWith('memory_') ? 120000 : 30000);
-            const response = await this.fetcher(new URL(path, endpoint(b.endpoint)), { method, headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}), ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'error', signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
+            const response = await this.fetcher(new URL(path, endpoint(target)), { method, headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}), ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'error', signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
+            // A rejected grant is dropped before any result handling, so the next call asks Portal again.
+            if (grant && (response.status === 401 || response.status === 403))
+                sharedGrants.delete(await this.grantKey(app));
             if (operation === 'memory_tools' || operation.startsWith('memory_native_')) {
                 const result = await boundedJson(response, 8388608);
                 if (!result || typeof result.ok !== 'boolean' || (!response.ok && result.ok))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/portal",
-  "version": "0.3.0-rc.4",
+  "version": "0.3.0-rc.5",
   "type": "module",
   "license": "MIT",
   "files": [