@segmentstream-cloud/ontology 0.25.0 → 0.25.1

package/dist/service/agent/attachments.d.ts

@@ -13,9 +13,10 @@ export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.js";
 /**
  * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
  * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
- * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * while they are active. The chat and the agent session come from the agent's runtime in
  * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
- * tool arguments; every operation is confined to that member, chat and session.
+ * tool arguments. Storage checks current group participation or chat administration; private files
+ * remain confined to their sender and session.
  */
 export declare const ATTACHMENTS_PATH = "/api/ontology/agent/attachments";
 export interface AttachmentRoutesOptions {

package/dist/service/agent/attachments.js

@@ -12,9 +12,10 @@ export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.js";
 /**
  * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
  * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
- * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * while they are active. The chat and the agent session come from the agent's runtime in
  * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
- * tool arguments; every operation is confined to that member, chat and session.
+ * tool arguments. Storage checks current group participation or chat administration; private files
+ * remain confined to their sender and session.
  */
 export const ATTACHMENTS_PATH = `${AGENT_PATH}/attachments`;
 const NO_STORE = { "cache-control": "no-store" };
@@ -111,6 +112,7 @@ export function attachmentsLayer(options) {
                 request,
                 agents,
                 verify: verifyRuntime,
+                allowUnpairedMember: true,
             });
             return authenticated.ok
                 ? yield* answer(request, authenticated.caller, attachments)

package/dist/service/agent/authentication.d.ts

@@ -6,11 +6,13 @@ import type { AgentStore } from "../runtime-contract.js";
 import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 export declare const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
 export declare const SESSION_HEADER = "x-segmentstream-agent-session";
-/** Both temporary attachments and stored files require the runtime and its paired member. */
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
 export declare function authenticateAgentCaller(input: {
     readonly request: HttpServerRequest.HttpServerRequest;
     readonly agents: AgentStore;
     readonly verify: RuntimeTokenVerifier;
+    /** Temporary attachments authorize active members against the chat registry, without a pairing. */
+    readonly allowUnpairedMember?: boolean;
 }): Effect.Effect<{
     readonly ok: false;
     readonly response: import("effect/unstable/http/HttpServerResponse").HttpServerResponse;

package/dist/service/agent/authentication.js

@@ -1,13 +1,13 @@
 import { Effect, Redacted } from "effect";
 import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
-import { RequestId, forbidden, toServerResponse, unauthorized, unavailable } from "../errors.js";
+import { RequestId, forbidden, notFound, toServerResponse, unauthorized, unavailable, } from "../errors.js";
 import { ACT_AS_HEADER, logRuntimeRejection, } from "../runtime-identity.js";
 export const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
 export const SESSION_HEADER = "x-segmentstream-agent-session";
 const CONVERSATION = /^[a-z][a-z0-9_-]{0,31}:[A-Za-z0-9:_-]{1,200}$/;
 const SESSION = /^[A-Za-z0-9:_.-]{1,200}$/;
-/** Both temporary attachments and stored files require the runtime and its paired member. */
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
 export function authenticateAgentCaller(input) {
     return Effect.gen(function* () {
         const { request, agents, verify } = input;
@@ -31,9 +31,15 @@ export function authenticateAgentCaller(input) {
         const actAs = request.headers[ACT_AS_HEADER]?.trim() ?? "";
         const conversation = request.headers[CONVERSATION_HEADER]?.trim() ?? "";
         const session = request.headers[SESSION_HEADER]?.trim() ?? "";
-        const member = actAs === "" ? undefined : yield* agents.actingMember(actAs);
+        const member = actAs === ""
+            ? undefined
+            : input.allowUnpairedMember
+                ? (yield* agents.member(actAs))?.principal
+                : yield* agents.actingMember(actAs);
         if (member === undefined) {
-            return denied(forbidden(requestId, "The member is inactive or has not paired with the agent."));
+            return denied(input.allowUnpairedMember
+                ? notFound(requestId, "Attachment not found.")
+                : forbidden(requestId, "The member is inactive or has not paired with the agent."));
         }
         if (!CONVERSATION.test(conversation) || (session !== "" && !SESSION.test(session))) {
             return denied(forbidden(requestId, "The agent names the chat and session of every request."));

package/dist/storage/attachments.d.ts

@@ -6,11 +6,12 @@ import type { Principal } from "../runtime.js";
 import type { BlobProvider, TransferGrant } from "./provider.js";
 /**
  * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
- * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
- * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
- * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
- * promote it into a record through an action, which adopts the same stored object without copying
- * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ * `_blobs` revision in the ontology's private file storage. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the agent may read it,
+ * discard it, or promote it into a record through an action, which adopts the same stored object
+ * without copying it. Every operation derives chat access from the caller and registry, never from
+ * tool input.
  */
 /** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
 export declare const MAX_ATTACHMENT_BYTES: number;
@@ -25,8 +26,8 @@ export interface AttachmentCaller {
     /** The chat the attachment arrived in, such as `telegram:12345`. */
     readonly conversation: string;
     /**
-     * The agent session the request comes from. The first session that reads an attachment owns it;
-     * other sessions of the same chat, such as one after a reset, never see it.
+     * The agent session the request comes from. Private attachments stay bound to the first session
+     * that reads them. Group attachments are shared across authorized sessions in the same chat.
      */
     readonly sessionId?: string;
 }

package/dist/storage/attachments.js

@@ -9,11 +9,12 @@ import { authorizeBlobOperation } from "./authorization.js";
 import { ATTACHMENTS_TABLE } from "./tables.js";
 /**
  * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
- * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
- * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
- * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
- * promote it into a record through an action, which adopts the same stored object without copying
- * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ * `_blobs` revision in the ontology's private file storage. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the agent may read it,
+ * discard it, or promote it into a record through an action, which adopts the same stored object
+ * without copying it. Every operation derives chat access from the caller and registry, never from
+ * tool input.
  */
 /** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
 export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
@@ -102,9 +103,34 @@ export function attachmentRuntime(ontology, sql, provider) {
     const binding = provider.binding;
     const missing = (id) => new NotFound({ entity: "attachment", id, message: "Attachment not found." });
     const unavailable = (message) => new Conflict({ entity: "attachment", message });
+    /** The registry contains groups only. Neither a tool argument nor a caller's roles name a group. */
+    const accessScope = (caller) => Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [caller.principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return "denied";
+        }
+        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        const separator = caller.conversation.indexOf(":");
+        const [chat] = yield* sql.unsafe(`SELECT id::text FROM "agent_chat"
+         WHERE provider = $1 AND external_id = $2 FOR SHARE`, [caller.conversation.slice(0, separator), caller.conversation.slice(separator + 1)]);
+        if (chat === undefined) {
+            return "private";
+        }
+        const [participant] = yield* sql.unsafe(`SELECT 1 FROM "agent_chat_members"
+         WHERE agent_chat_id = $1::uuid AND user_id = $2::uuid FOR SHARE`, [chat.id, caller.principal.id]);
+        if (participant !== undefined) {
+            return "group";
+        }
+        // App roles are authored by the workspace. Chat management grants its administrator access;
+        // re-read the roles here rather than trusting permissions cached on the principal.
+        const administrator = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        return administrator ? "group" : "denied";
+    });
     /**
-     * The caller's attachment, locked. Another member's, another chat's or another session's is not
-     * found: it does not exist for this caller. The first session that loads it owns it.
+     * The caller's attachment, locked. Group access follows current chat membership. Private access
+     * requires the sender and their session. Source transfers always require the original sender.
      */
     const load = (id, caller, 
     /** `source`: the webhook redelivering the file it stored, before or after a session read it. */
@@ -112,23 +138,37 @@ export function attachmentRuntime(ontology, sql, provider) {
         if (!/^[0-9a-f-]{36}$/i.test(id)) {
             return yield* missing(id);
         }
-        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND a.owner_id = $2::uuid AND a.conversation = $3
-          AND a.branch_id = $4 FOR UPDATE OF a, b`, [id, caller.principal.id, caller.conversation, binding.branchId]);
+        const access = yield* accessScope(caller);
+        if (access === "denied") {
+            return yield* missing(id);
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND (a.owner_id = $2::uuid OR $5) AND a.conversation = $3
+          AND a.branch_id = $4 FOR UPDATE OF a, b`, [
+            id,
+            caller.principal.id,
+            caller.conversation,
+            binding.branchId,
+            access === "group" && scope === "session",
+        ]);
         const row = rows[0];
         if (!row) {
             return yield* missing(id);
         }
-        if (scope === "session" && row.session_id !== null && row.session_id !== caller.sessionId) {
+        if (access === "private" &&
+            scope === "session" &&
+            row.session_id !== null &&
+            row.session_id !== caller.sessionId) {
             return yield* missing(id);
         }
-        if (scope === "session" && row.session_id === null && caller.sessionId !== undefined) {
+        if (access === "private" &&
+            scope === "session" &&
+            row.session_id === null &&
+            caller.sessionId !== undefined) {
             yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET session_id = $1 WHERE id = $2::uuid`, [
                 caller.sessionId,
                 row.id,
             ]);
         }
-        // The member must still be active; a deactivated member's agent reads nothing.
-        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [], caller.principal.execution);
         return row;
     });
     /**
@@ -203,7 +243,7 @@ export function attachmentRuntime(ontology, sql, provider) {
                 input.size,
                 input.sha256,
             ]);
-            return yield* load(id, caller);
+            return yield* load(id, caller, "source");
         }));
         if (reserved.state !== "received" || reserved.expired) {
             return { attachment: view(reserved) };
@@ -232,7 +272,7 @@ export function attachmentRuntime(ontology, sql, provider) {
     });
     /** Completes the transfer, then verifies the stored bytes against the declared size and digest. */
     const complete = (id, caller) => Effect.gen(function* () {
-        const row = yield* sql.withTransaction(load(id, caller));
+        const row = yield* sql.withTransaction(load(id, caller, "source"));
         if (row.state !== "received") {
             return READABLE.has(row.state) && !row.expired
                 ? view(row)
@@ -267,16 +307,25 @@ export function attachmentRuntime(ontology, sql, provider) {
         return yield* sql.withTransaction(Effect.gen(function* () {
             yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'ready'
              WHERE id = $1::uuid AND state = 'received'`, [row.id]);
-            return view(yield* load(row.id, caller));
+            return view(yield* load(row.id, caller, "source"));
         }));
     });
-    /** The caller's attachments in this chat and session that are still readable, newest first. */
+    /** Accessible attachments in this chat that are still readable, newest first. */
     const list = (caller) => sql.withTransaction(Effect.gen(function* () {
-        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [], caller.principal.execution);
-        const rows = yield* sql.unsafe(`${SELECT} WHERE a.owner_id = $1::uuid AND a.conversation = $2 AND a.branch_id = $3
+        const access = yield* accessScope(caller);
+        if (access === "denied") {
+            return [];
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE (a.owner_id = $1::uuid OR $5) AND a.conversation = $2 AND a.branch_id = $3
              AND a.state IN ('ready', 'promoted') AND a.expires_at > now()
-             AND (a.session_id IS NULL OR a.session_id = $4)
-           ORDER BY a.created_at DESC LIMIT ${MAX_LIVE_ATTACHMENTS}`, [caller.principal.id, caller.conversation, binding.branchId, caller.sessionId ?? null]);
+             AND ($5 OR a.session_id IS NULL OR a.session_id = $4)
+           ORDER BY a.created_at DESC LIMIT ${MAX_LIVE_ATTACHMENTS}`, [
+            caller.principal.id,
+            caller.conversation,
+            binding.branchId,
+            caller.sessionId ?? null,
+            access === "group",
+        ]);
         return rows.map(view);
     }));
     /**
@@ -351,6 +400,7 @@ export function attachmentRuntime(ontology, sql, provider) {
         const qualified = `${target.entity}.${target.action}`;
         const prepared = yield* sql.withTransaction(Effect.gen(function* () {
             const row = yield* load(id, caller);
+            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
             if (row.state === "promoted") {
                 return { kind: "done", row };
             }
@@ -365,11 +415,21 @@ export function attachmentRuntime(ontology, sql, provider) {
                         `${row.content_type}, ${row.size} bytes.`,
                 });
             }
-            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
             const [earlier] = yield* sql.unsafe(`SELECT id::text, promotion FROM "${ATTACHMENTS_TABLE}"
              WHERE sha256 = $1 AND branch_id = $2 AND state = 'promoted' AND id <> $3::uuid
                AND promotion->>'action' = $4 AND promotion->>'deduplicated_from' IS NULL
-             ORDER BY created_at LIMIT 1`, [row.sha256, binding.branchId, row.id, qualified]);
+               AND conversation = $5 AND (owner_id = $6::uuid OR $7)
+               AND ($7 OR session_id IS NULL OR session_id = $8)
+             ORDER BY created_at LIMIT 1`, [
+                row.sha256,
+                binding.branchId,
+                row.id,
+                qualified,
+                caller.conversation,
+                caller.principal.id,
+                (yield* accessScope(caller)) === "group",
+                caller.sessionId ?? null,
+            ]);
             if (earlier) {
                 const promotion = {
                     ...earlier.promotion,

package/dist/storage/tables.d.ts

@@ -5,6 +5,7 @@ export declare const ATTACHMENTS_TABLE = "_agent_attachments";
 /**
  * A file a member sent the app's agent: platform metadata, never an ontology record. The bytes are
  * a `_blobs` revision in the same storage as uploads; the row binds them to their owner, the chat
- * and the agent session that received them, and expires 24 hours after receipt unless promoted.
+ * and, for private chats, the first agent session that reads them. Group access follows the chat
+ * registry's current members. Attachments expire 24 hours after receipt unless promoted.
  */
 export declare const ATTACHMENT_TABLES_DDL: ReadonlyArray<string>;

package/dist/storage/tables.js

@@ -58,7 +58,8 @@ export const ATTACHMENTS_TABLE = "_agent_attachments";
 /**
  * A file a member sent the app's agent: platform metadata, never an ontology record. The bytes are
  * a `_blobs` revision in the same storage as uploads; the row binds them to their owner, the chat
- * and the agent session that received them, and expires 24 hours after receipt unless promoted.
+ * and, for private chats, the first agent session that reads them. Group access follows the chat
+ * registry's current members. Attachments expire 24 hours after receipt unless promoted.
  */
 export const ATTACHMENT_TABLES_DDL = [
     `CREATE TABLE IF NOT EXISTS "${ATTACHMENTS_TABLE}" (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",