@adonis-agora/agent 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/agent
 
+## 0.8.0
+
+### Minor Changes
+
+- [#23](https://github.com/DavideCarvalho/adonis-agent/pull/23) [`19c9ffd`](https://github.com/DavideCarvalho/adonis-agent/commit/19c9ffd9c285c7cab4e487c8bda73f7ce668be9e) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `authzActorResolver` (exported from `@adonis-agora/agent/authz`) — resolve the agent `Actor` from the Agora context populated by authkit (`userRef`, `tenantId`) plus authz `effectiveRoles` (the union global ∪ app ∪ store). Structural, zero hard dependency; authkit+authz apps can drop hand-written actor resolvers. Fail-closed: no identity in context → 401.
+
 ## 0.7.1
 
 ### Patch Changes

package/dist/src/authz/agora-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structural, dependency-free reader for the Agora runtime context — mirrors
+ * `@adonis-agora/authz`'s `agora/context.ts`. The Agora context library publishes a READ accessor
+ * on the well-known symbol slot. We never import that package; when the slot is absent (context not
+ * installed) the reader degrades to `undefined` and the caller fails closed.
+ */
+/** The symbol slot the Agora context library writes its read accessor into. */
+export declare const AGORA_CONTEXT_ACCESSOR: unique symbol;
+/**
+ * The slice of the context accessor this package reads. `userRef` and `tenantId` are direct
+ * accessor fields (authkit writes them via the `set` slot); we never read `globalRoles` here —
+ * authz's `effectiveRoles` does that internally.
+ */
+export interface AgoraContextAccessor {
+    tenantId?: string;
+    userRef?: {
+        type?: string;
+        id?: string | number;
+    };
+    get?: () => unknown;
+}
+/** Read the active Agora context accessor from the global slot, if present. */
+export declare function readContextAccessor(): AgoraContextAccessor | undefined;
+//# sourceMappingURL=agora-context.d.ts.map

package/dist/src/authz/agora-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agora-context.d.ts","sourceRoot":"","sources":["../../../src/authz/agora-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,eAAwC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAItE"}

package/dist/src/authz/agora-context.js

@@ -0,0 +1,16 @@
+/**
+ * Structural, dependency-free reader for the Agora runtime context — mirrors
+ * `@adonis-agora/authz`'s `agora/context.ts`. The Agora context library publishes a READ accessor
+ * on the well-known symbol slot. We never import that package; when the slot is absent (context not
+ * installed) the reader degrades to `undefined` and the caller fails closed.
+ */
+/** The symbol slot the Agora context library writes its read accessor into. */
+export const AGORA_CONTEXT_ACCESSOR = Symbol.for('@agora/context:accessor');
+/** Read the active Agora context accessor from the global slot, if present. */
+export function readContextAccessor() {
+    const slot = globalThis[AGORA_CONTEXT_ACCESSOR];
+    if (slot == null || typeof slot !== 'object')
+        return undefined;
+    return slot;
+}
+//# sourceMappingURL=agora-context.js.map

package/dist/src/authz/agora-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agora-context.js","sourceRoot":"","sources":["../../../src/authz/agora-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAa5E,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAI,UAAsC,CAAC,sBAAsB,CAAC,CAAC;IAC7E,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/D,OAAO,IAA4B,CAAC;AACtC,CAAC"}

package/dist/src/authz/authz-actor-resolver.d.ts

@@ -0,0 +1,35 @@
+import type { ActorResolver } from '../spi/actor-resolver.js';
+import type { Actor } from '../types.js';
+import type { AuthzTenantScope } from './authz-tool-authorizer.js';
+/**
+ * The structural slice of `@adonis-agora/authz`'s `AuthzService` this resolver needs: the user's
+ * effective roles (authz's union of global (context) ∪ app (`resolveRoles`) ∪ store (DB)). Typed
+ * structurally so `@adonis-agora/authz` stays an OPTIONAL lazy peer — zero import of the package.
+ */
+export interface AuthzRolesSourceLike {
+    effectiveRoles(user: unknown, scope?: AuthzTenantScope): Promise<string[]>;
+}
+/** Options for {@link AuthzActorResolver} / {@link authzActorResolver}. */
+export interface AuthzActorResolverConfig {
+    /** The `@adonis-agora/authz` `AuthzService` (or any structural match) the resolver reads roles from. */
+    authz: AuthzRolesSourceLike;
+}
+/**
+ * An {@link ActorResolver} that reads the caller from the Agora context authkit populates
+ * (`userRef`, `tenantId`) and takes the caller's roles from authz (`effectiveRoles`). It ignores
+ * the transport `req` and reads the active Agora context store, so it needs no `ctx.auth` and is
+ * framework-agnostic.
+ *
+ * Security posture — FAIL-CLOSED: no `userRef.id` in context → throws (the provider replies 401).
+ * An identity is never fabricated. The context `userRef` is passed straight to `effectiveRoles`;
+ * authz reads its `.id`/`.type` and re-reads `globalRoles` from the same context, so global roles
+ * (e.g. `ADMIN`) land in the result with no extra wiring.
+ */
+export declare class AuthzActorResolver implements ActorResolver {
+    #private;
+    constructor(config: AuthzActorResolverConfig);
+    resolve(_req: unknown): Promise<Actor>;
+}
+/** Factory for {@link AuthzActorResolver}. */
+export declare function authzActorResolver(config: AuthzActorResolverConfig): ActorResolver;
+//# sourceMappingURL=authz-actor-resolver.d.ts.map

package/dist/src/authz/authz-actor-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-actor-resolver.d.ts","sourceRoot":"","sources":["../../../src/authz/authz-actor-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5E;AAED,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,wGAAwG;IACxG,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,aAAa;;gBAG1C,MAAM,EAAE,wBAAwB;IAItC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;CAsB7C;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,aAAa,CAElF"}

package/dist/src/authz/authz-actor-resolver.js

@@ -0,0 +1,41 @@
+import { readContextAccessor } from './agora-context.js';
+/**
+ * An {@link ActorResolver} that reads the caller from the Agora context authkit populates
+ * (`userRef`, `tenantId`) and takes the caller's roles from authz (`effectiveRoles`). It ignores
+ * the transport `req` and reads the active Agora context store, so it needs no `ctx.auth` and is
+ * framework-agnostic.
+ *
+ * Security posture — FAIL-CLOSED: no `userRef.id` in context → throws (the provider replies 401).
+ * An identity is never fabricated. The context `userRef` is passed straight to `effectiveRoles`;
+ * authz reads its `.id`/`.type` and re-reads `globalRoles` from the same context, so global roles
+ * (e.g. `ADMIN`) land in the result with no extra wiring.
+ */
+export class AuthzActorResolver {
+    #authz;
+    constructor(config) {
+        this.#authz = config.authz;
+    }
+    async resolve(_req) {
+        const accessor = readContextAccessor();
+        const ref = accessor?.userRef;
+        if (ref?.id === undefined || ref.id === null || String(ref.id).length === 0) {
+            throw new Error('authzActorResolver: no authenticated identity in @agora/context. The agent route must ' +
+                'sit behind authkit auth middleware (which populates the context), with the ' +
+                '@adonis-agora/context provider registered.');
+        }
+        const scope = accessor?.tenantId
+            ? { tenantId: accessor.tenantId }
+            : undefined;
+        const roles = await this.#authz.effectiveRoles(ref, scope);
+        return {
+            id: String(ref.id),
+            roles,
+            ...(accessor?.tenantId ? { tenantRef: accessor.tenantId } : {}),
+        };
+    }
+}
+/** Factory for {@link AuthzActorResolver}. */
+export function authzActorResolver(config) {
+    return new AuthzActorResolver(config);
+}
+//# sourceMappingURL=authz-actor-resolver.js.map

package/dist/src/authz/authz-actor-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-actor-resolver.js","sourceRoot":"","sources":["../../../src/authz/authz-actor-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkBzD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAkB;IACpB,MAAM,CAAuB;IAEtC,YAAY,MAAgC;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAa;QACzB,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,QAAQ,EAAE,OAAO,CAAC;QAC9B,IAAI,GAAG,EAAE,EAAE,KAAK,SAAS,IAAI,GAAG,CAAC,EAAE,KAAK,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5E,MAAM,IAAI,KAAK,CACb,wFAAwF;gBACtF,6EAA6E;gBAC7E,4CAA4C,CAC/C,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAiC,QAAQ,EAAE,QAAQ;YAC5D,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YACjC,CAAC,CAAC,SAAS,CAAC;QACd,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE3D,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,KAAK;YACL,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB,CAAC,MAAgC;IACjE,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/src/authz/index.d.ts

@@ -1,3 +1,5 @@
 export { AuthzToolAuthorizer, authzToolAuthorizer, defaultUserFromActor, } from './authz-tool-authorizer.js';
 export type { AuthzToolAuthorizerConfig, AuthzServiceLike, AuthzTenantScope, } from './authz-tool-authorizer.js';
+export { AuthzActorResolver, authzActorResolver } from './authz-actor-resolver.js';
+export type { AuthzActorResolverConfig, AuthzRolesSourceLike } from './authz-actor-resolver.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/authz/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACnF,YAAY,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/authz/index.js

@@ -1,2 +1,3 @@
 export { AuthzToolAuthorizer, authzToolAuthorizer, defaultUserFromActor, } from './authz-tool-authorizer.js';
+export { AuthzActorResolver, authzActorResolver } from './authz-actor-resolver.js';
 //# sourceMappingURL=index.js.map

package/dist/src/authz/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.7.1";
+export declare const VERSION = "0.8.0";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './spi/model-provider.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.7.1';
+export const VERSION = '0.8.0';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './spi/model-provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {