@hivemagnus/ardent-studio 0.2.0 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@ project event stream.
 | [Oathweave](https://github.com/ChefTaco/Oathweave) | Yes | Sign-in for people (audience `ardentstudio`) and ArdentStudio's own service identity. |
 | ChatterMost | No | Optional one-way announcements through an incoming webhook. |
 
-Node.js 24.22.1+ or 26.13.0+.
+Node.js 24.22.3+ or 26.13.1+.
 
 ## Architecture
 

package/dist/auth/{oathweave.d.ts → authenticator.d.ts}

@@ -1,4 +1,4 @@
-import { type JWTVerifyGetKey } from 'jose';
+import type { JWTVerifyGetKey } from 'jose';
 import { type ArdentStudioPermission } from '../shared/browser.js';
 import { type IdentityLink } from './links.js';
 export interface OathweaveOptions {
@@ -35,7 +35,15 @@ export declare class AccessDenied extends Error {
 export declare const SESSION_CACHE_TTL_MS = 10000;
 /** How often an open stream re-checks its token. */
 export declare const STREAM_RECHECK_MS = 5000;
-export declare function isHttpsEndpoint(value: string): boolean;
+/**
+ * Studio has always checked token times exactly; the shared verifier would allow 30 s of skew.
+ * Kept at zero so this change does not widen what Studio accepts.
+ */
+export declare const CLOCK_TOLERANCE_SEC = 0;
+/**
+ * Build Studio's verifier on the shared one. Every refusal is an OathweaveError with a stable
+ * `reason`; the router maps all of them (including an unreachable JWKS or userinfo) to 401.
+ */
 export declare function createOathweaveVerifier(options: OathweaveOptions, overrides?: {
     keys?: JWTVerifyGetKey;
     fetch?: typeof fetch;

package/dist/auth/authenticator.js

@@ -0,0 +1,66 @@
+// Oathweave resource-token verification for ArdentStudio, using the suite's shared verifier
+// (@hivemagnus/hive-common/oathweave): RS256 only, exact issuer and audience, at most fifteen
+// minutes, USER actor with a session, and an online session check through userinfo.
+// Failure is closed. Studio accepts people only; service tokens are refused.
+import { createOathweaveVerifier as createSharedVerifier, OATHWEAVE_SESSION_CACHE_TTL_MS, OATHWEAVE_STREAM_RECHECK_MS, } from '@hivemagnus/hive-common/oathweave';
+import { ARDENT_STUDIO_AUDIENCE } from '../shared/browser.js';
+import { effectivePermissions, linkFor } from './links.js';
+/** The token is valid but its subject has no explicit link, so the person has no Studio access. */
+export class AccessDenied extends Error {
+    name = 'AccessDenied';
+}
+/** How long a userinfo answer is reused, measured from when the request started. */
+export const SESSION_CACHE_TTL_MS = OATHWEAVE_SESSION_CACHE_TTL_MS;
+/** How often an open stream re-checks its token. */
+export const STREAM_RECHECK_MS = OATHWEAVE_STREAM_RECHECK_MS;
+/**
+ * Studio has always checked token times exactly; the shared verifier would allow 30 s of skew.
+ * Kept at zero so this change does not widen what Studio accepts.
+ */
+export const CLOCK_TOLERANCE_SEC = 0;
+/**
+ * Build Studio's verifier on the shared one. Every refusal is an OathweaveError with a stable
+ * `reason`; the router maps all of them (including an unreachable JWKS or userinfo) to 401.
+ */
+export function createOathweaveVerifier(options, overrides = {}) {
+    const verifier = createSharedVerifier({
+        issuer: options.issuer,
+        audience: options.audience ?? ARDENT_STUDIO_AUDIENCE,
+        jwksUrl: options.jwksUrl,
+        userinfoUrl: options.userinfoUrl,
+        accept: 'user',
+        clockToleranceSec: CLOCK_TOLERANCE_SEC,
+        ...(overrides.keys ? { keys: overrides.keys } : {}),
+        ...(overrides.fetch ? { fetch: overrides.fetch } : {}),
+        ...(overrides.now ? { now: overrides.now } : {}),
+    });
+    return async (token) => {
+        const principal = await verifier.verifyUser(token);
+        return {
+            subject: principal.subject,
+            issuer: principal.issuer,
+            sessionId: principal.sessionId,
+            permissions: [...principal.permissions],
+            displayName: principal.displayName,
+            issuedAt: principal.issuedAt,
+            expiresAt: principal.expiresAt,
+        };
+    };
+}
+/** Verify a bearer token and map it through its one explicit identity link. */
+export function createAuthenticator(verify, links) {
+    return async (token) => {
+        const identity = await verify(token);
+        const link = linkFor(links, identity.issuer, identity.subject);
+        if (!link)
+            throw new AccessDenied('An explicit unique account link is required');
+        return {
+            userId: link.localUserId,
+            subject: identity.subject,
+            issuer: identity.issuer,
+            displayName: link.displayName ?? identity.displayName,
+            permissions: effectivePermissions(link, identity.permissions),
+            expiresAt: identity.expiresAt,
+        };
+    };
+}

package/dist/clients/hivemem.d.ts

@@ -53,11 +53,12 @@ export interface HiveMemClientOptions {
     tokens: Pick<ServiceTokenProvider, 'token' | 'invalidate'>;
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /** Extra headers per request; defaults to the current request context (x-request-id, traceparent). */
+    headers?: () => Record<string, string>;
 }
 export declare class HiveMemClient {
-    private readonly options;
-    private readonly request;
-    private readonly baseUrl;
+    private readonly sdk;
+    private readonly probe;
     constructor(options: HiveMemClientOptions);
     /** Unauthenticated liveness of the HiveMem service. */
     health(): Promise<{
@@ -81,5 +82,4 @@ export declare class HiveMemClient {
         preview: KnowledgeSyncResponse;
         applied: KnowledgeSyncResponse;
     }>;
-    private call;
 }

package/dist/clients/hivemem.js

@@ -2,7 +2,10 @@
 // as a revision-aware source (POST /v1/knowledge/sources/sync). ArdentStudio calls it with its
 // own Oathweave service identity (audience `hivemem`), linked in HiveMem's
 // HIVEMEM_OATHWEAVE_SERVICES_JSON with the memories:write and workspaces:write scopes.
+// The HTTP layer is @hivemagnus/hivemem-sdk; this module keeps Studio's own interface on top of it.
 import { createHash } from 'node:crypto';
+import { outboundHeaders } from '@hivemagnus/hive-common/context';
+import { HiveMem, HiveMemHTTPError } from '@hivemagnus/hivemem-sdk';
 import { z } from 'zod';
 import { trimTrailingSlashes } from '../url.js';
 export class HiveMemError extends Error {
@@ -32,32 +35,72 @@ export const HIVEMEM_MAX_SYNC_BYTES = 4 * 1024 * 1024;
 export function chunkHash(content) {
     return createHash('sha256').update(content).digest('hex');
 }
+/** Studio's errors: the server's `detail` (or `error`), else the HTTP status. */
+function translate(error) {
+    if (!(error instanceof HiveMemHTTPError))
+        return error;
+    const details = error.details;
+    const message = typeof details?.detail === 'string' ? details.detail : typeof details?.error === 'string' ? details.error : `HiveMem answered HTTP ${error.statusCode}`;
+    return new HiveMemError(message.slice(0, 300), error.statusCode);
+}
+async function sdkCall(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        throw translate(error);
+    }
+}
+/**
+ * The SDK reads an error body as JSON and then as text, which fails on a non-JSON body (a proxy
+ * page, for example). Hand it an empty JSON body instead so the error still carries its status.
+ */
+function jsonErrorBodies(request) {
+    return async (input, init) => {
+        const response = await request(input, init);
+        if (response.ok || response.headers.get('content-type')?.includes('json'))
+            return response;
+        await response.body?.cancel().catch(() => undefined);
+        return new Response('null', { status: response.status, statusText: response.statusText, headers: { 'content-type': 'application/json' } });
+    };
+}
 export class HiveMemClient {
-    options;
-    request;
-    baseUrl;
+    sdk;
+    probe;
     constructor(options) {
-        this.options = options;
-        this.request = options.fetch ?? ((input, init) => fetch(input, init));
-        this.baseUrl = trimTrailingSlashes(options.baseUrl);
+        const request = options.fetch ?? ((input, init) => fetch(input, init));
+        const fetchImpl = jsonErrorBodies(request);
+        const headers = options.headers ?? (() => outboundHeaders());
+        this.sdk = new HiveMem({
+            baseUrl: trimTrailingSlashes(options.baseUrl),
+            fetchImpl,
+            headers,
+            // Studio keeps its own retry schedule for knowledge sync; the SDK only retries once after a 401.
+            maxRetries: 0,
+            timeoutMs: options.timeoutMs ?? 30_000,
+            tokenProvider: async ({ forceRefresh }) => {
+                if (forceRefresh)
+                    options.tokens.invalidate();
+                return options.tokens.token();
+            },
+        });
+        // Health is unauthenticated: an empty token keeps the SDK from reading one from the environment.
+        this.probe = new HiveMem({ baseUrl: this.sdk.baseUrl, fetchImpl, headers, token: '', maxRetries: 0, timeoutMs: 5_000 });
     }
     /** Unauthenticated liveness of the HiveMem service. */
     async health() {
-        const response = await this.request(`${this.baseUrl}/v1/health`, { redirect: 'error', signal: AbortSignal.timeout(5_000) });
-        if (!response.ok)
-            throw new HiveMemError(`HiveMem health answered HTTP ${response.status}`, response.status);
-        return z.object({ status: z.string() }).loose().parse(await response.json());
+        return z.object({ status: z.string() }).loose().parse(await sdkCall(() => this.probe.health()));
     }
     /** Create the project workspace. HiveMem returns the existing workspace when it already exists. */
     async ensureWorkspace(input) {
-        return workspaceSchema.parse(await this.call('POST', '/v1/workspaces', {
-            workspace_id: input.workspace_id, title: input.title.slice(0, 200), description: input.description ?? null, metadata: input.metadata ?? {},
-        }));
+        return workspaceSchema.parse(await sdkCall(() => this.sdk.createWorkspace(input.workspace_id, {
+            title: input.title.slice(0, 200), description: input.description ?? null, metadata: input.metadata ?? {},
+        })));
     }
     async syncKnowledgeSource(body) {
         if (body.chunks.length > HIVEMEM_MAX_CHUNKS)
             throw new HiveMemError(`A source sync holds at most ${HIVEMEM_MAX_CHUNKS} chunks`, 400);
-        return knowledgeSyncResponseSchema.parse(await this.call('POST', '/v1/knowledge/sources/sync', body));
+        return knowledgeSyncResponseSchema.parse(await sdkCall(() => this.sdk.syncKnowledgeSource({ ...body })));
     }
     /** Validate, then write: a preview proves the request before anything changes. */
     async syncKnowledgeSourceChecked(body) {
@@ -65,25 +108,4 @@ export class HiveMemClient {
         const applied = await this.syncKnowledgeSource({ ...body, mode: 'apply' });
         return { preview, applied };
     }
-    async call(method, path, body) {
-        const attempt = async () => this.request(`${this.baseUrl}${path}`, {
-            method,
-            headers: { authorization: `Bearer ${await this.options.tokens.token()}`, accept: 'application/json', ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
-            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-            redirect: 'error',
-            signal: AbortSignal.timeout(this.options.timeoutMs ?? 30_000),
-        });
-        let response = await attempt();
-        if (response.status === 401) {
-            await response.body?.cancel();
-            this.options.tokens.invalidate();
-            response = await attempt();
-        }
-        if (!response.ok) {
-            const detail = await response.json().catch(() => null);
-            const message = typeof detail?.detail === 'string' ? detail.detail : typeof detail?.error === 'string' ? detail.error : `HiveMem answered HTTP ${response.status}`;
-            throw new HiveMemError(message.slice(0, 300), response.status);
-        }
-        return response.status === 204 ? null : response.json();
-    }
 }

package/dist/db/repos/team.d.ts

@@ -43,6 +43,8 @@ export declare class TeamRepository {
         role_key: string;
         role_name: string;
     }>;
+    /** Ids of the projects where an agent is bound to a role in the published or the draft team. */
+    projectsForAgent(agentRef: string): Set<string>;
     ensureBinding(agentRef: string, displayName?: string | null): AgentBinding;
     binding(agentRef: string): AgentBinding | undefined;
     bindings(): AgentBinding[];

package/dist/db/repos/team.js

@@ -77,6 +77,13 @@ export class TeamRepository {
             .filter(role => role.agent_ref)
             .map(role => ({ agent_ref: role.agent_ref, project_id: row.project_id, project_name: row.project_name, role_key: role.key, role_name: role.name })));
     }
+    /** Ids of the projects where an agent is bound to a role in the published or the draft team. */
+    projectsForAgent(agentRef) {
+        const rows = this.db.prepare(`SELECT DISTINCT r.project_id FROM team_assignments a
+      JOIN team_assignment_revisions r ON r.project_id = a.project_id AND r.revision IN (a.current_revision, a.draft_revision)
+      WHERE EXISTS (SELECT 1 FROM json_each(r.body_json, '$.roles') role WHERE json_extract(role.value, '$.agent_ref') = ?)`).all(agentRef);
+        return new Set(rows.map(row => row.project_id));
+    }
     // ── Agent bindings: a stable Studio id per Magnus-managed agent ──
     ensureBinding(agentRef, displayName) {
         const now = this.clock.now().toISOString();

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { MagnusClient, MagnusError, parseAgentRef, agentRef, STUDIO_ACTIONS, REL
 export { HiveMemClient, HiveMemError } from './clients/hivemem.js';
 export { ChatterMostClient } from './clients/chattermost.js';
 export { ServiceTokenProvider } from './clients/service-token.js';
-export { createOathweaveVerifier, createAuthenticator, AccessDenied, type Principal } from './auth/oathweave.js';
+export { createOathweaveVerifier, createAuthenticator, AccessDenied, type Principal } from './auth/authenticator.js';
 export { parseIdentityLinks, type IdentityLink } from './auth/links.js';
 export { validateTeam, type ValidationInput, type ValidationResult } from './team/validation.js';
 export { TEAM_SEEDS, loadSeedTemplates } from './templates/seeds.js';

package/dist/index.js

@@ -9,7 +9,7 @@ export { MagnusClient, MagnusError, parseAgentRef, agentRef, STUDIO_ACTIONS, REL
 export { HiveMemClient, HiveMemError } from './clients/hivemem.js';
 export { ChatterMostClient } from './clients/chattermost.js';
 export { ServiceTokenProvider } from './clients/service-token.js';
-export { createOathweaveVerifier, createAuthenticator, AccessDenied } from './auth/oathweave.js';
+export { createOathweaveVerifier, createAuthenticator, AccessDenied } from './auth/authenticator.js';
 export { parseIdentityLinks } from './auth/links.js';
 export { validateTeam } from './team/validation.js';
 export { TEAM_SEEDS, loadSeedTemplates } from './templates/seeds.js';

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export type Logger = Record<LogLevel, (message: string, fields?: Record<string, unknown>) => void>;
-/** JSON lines on stderr. Callers never pass secrets, tokens or file contents. */
+/** JSON lines on stderr, with the request ID inside a request. Callers never pass secrets, tokens or file contents. */
 export declare function createLogger(level?: LogLevel, write?: (line: string) => void): Logger;
 export declare const silentLogger: Logger;

package/dist/logger.js

@@ -1,10 +1,12 @@
+import { getRequestContext } from '@hivemagnus/hive-common/context';
 const ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
-/** JSON lines on stderr. Callers never pass secrets, tokens or file contents. */
+/** JSON lines on stderr, with the request ID inside a request. Callers never pass secrets, tokens or file contents. */
 export function createLogger(level = 'info', write = line => process.stderr.write(`${line}\n`)) {
     const log = (at) => (message, fields = {}) => {
         if (ORDER[at] < ORDER[level])
             return;
-        write(JSON.stringify({ at: new Date().toISOString(), level: at, message, ...fields }));
+        const requestId = getRequestContext()?.requestId;
+        write(JSON.stringify({ at: new Date().toISOString(), level: at, message, ...(requestId ? { requestId } : {}), ...fields }));
     };
     return { debug: log('debug'), info: log('info'), warn: log('warn'), error: log('error') };
 }

package/dist/server/app.js

@@ -1,3 +1,4 @@
+import { requestContext } from '@hivemagnus/hive-common/hono';
 import { Hono } from 'hono';
 import { ARDENT_STUDIO_API_PREFIX } from '../shared/browser.js';
 import { errorResponse } from './errors.js';
@@ -17,6 +18,9 @@ import { workRoutes } from './routes/work.js';
 /** The ArdentStudio HTTP API under /api/ardentstudio/v1. */
 export function createApp(deps) {
     const app = new Hono();
+    // x-request-id (or x-hive-request-id / x-correlation-id) and W3C traceparent: read, generated
+    // when absent, echoed as x-request-id, and attached to log lines written during the request.
+    app.use('*', requestContext());
     app.use('*', async (c, next) => {
         await next();
         c.header('x-content-type-options', 'nosniff');

package/dist/server/deps.d.ts

@@ -1,6 +1,6 @@
 import type { AgentDirectory } from '../agents/directory.js';
 import type { OperationRelay } from '../agents/operations.js';
-import type { Authenticator, Principal } from '../auth/oathweave.js';
+import type { Authenticator, Principal } from '../auth/authenticator.js';
 import type { BlobStore } from '../blobs/store.js';
 import type { HiveMemClient } from '../clients/hivemem.js';
 import type { MagnusClient } from '../clients/magnus.js';

package/dist/server/env.d.ts

@@ -1,4 +1,4 @@
-import type { Principal } from '../auth/oathweave.js';
+import type { Principal } from '../auth/authenticator.js';
 export interface AppEnv {
     Variables: {
         principal: Principal | undefined;

package/dist/server/routes/health.js

@@ -1,28 +1,52 @@
+// Health runs on the suite's shared readiness helper (@hivemagnus/hive-common/health), but keeps
+// Studio's published body shape: HiveXUI parses it through the browser contract.
+import { readiness } from '@hivemagnus/hive-common/health';
 const CACHE_MS = 10_000;
-const failed = (error) => ({ status: 'unavailable', error: error instanceof Error ? error.message.slice(0, 200) : 'unavailable' });
+/** Above the Magnus client's own 20 s timeout, so the clients' timeouts decide, as before. */
+const CHECK_TIMEOUT_MS = 25_000;
+const toCheck = (report, maxError = 200) => report?.status === 'up'
+    ? { status: 'ok', error: null }
+    : { status: 'unavailable', error: (report?.error ?? 'unavailable').slice(0, maxError) };
 export function healthRoutes(register, deps) {
     let cached;
+    // Liveness never touches dependencies. Its body stays Studio's published `{status:'ok'}`.
     register('GET', '/health/live', () => ({ body: { status: 'ok' } }));
     register('GET', '/health/ready', async (c) => {
         if (!cached || Date.now() - cached.at > CACHE_MS) {
-            let database = { status: 'ok', error: null };
-            try {
-                deps.store.db.prepare('SELECT 1').get();
-            }
-            catch (error) {
-                database = failed(error);
-            }
-            const [agents, hivemem] = await Promise.all([
-                deps.agents.list().then(list => list.magnus.state === 'ok'
-                    ? { magnus: { status: 'ok', error: null }, available: list.available_count }
-                    : { magnus: { status: 'unavailable', error: list.magnus.error }, available: 0 }),
-                deps.hivemem.health().then(() => ({ status: 'ok', error: null }), failed),
-            ]);
-            // Ardent Project Studio requires at least one reachable Ardent agent.
-            const ready = database.status === 'ok' && agents.magnus.status === 'ok' && hivemem.status === 'ok' && agents.available > 0;
+            // One Magnus listing serves both the magnus and the agents checks.
+            const listing = deps.agents.list();
+            listing.catch(() => undefined);
+            const report = await readiness({
+                timeoutMs: CHECK_TIMEOUT_MS,
+                exposeErrors: true,
+                checks: [
+                    { name: 'database', check: () => { deps.store.db.prepare('SELECT 1').get(); } },
+                    { name: 'magnus', check: async () => {
+                            const list = await listing;
+                            if (list.magnus.state !== 'ok')
+                                throw new Error(list.magnus.error ?? 'unavailable');
+                        } },
+                    { name: 'hivemem', check: async () => { await deps.hivemem.health(); } },
+                    // Ardent Project Studio requires at least one reachable Ardent agent.
+                    { name: 'agents', check: async () => {
+                            const list = await listing;
+                            const available = list.magnus.state === 'ok' ? list.available_count : 0;
+                            return { ok: available > 0, details: { available } };
+                        } },
+                ],
+            });
+            const { checks } = report.body;
+            const agents = checks['agents'];
+            const available = typeof agents?.details?.['available'] === 'number' ? agents.details['available'] : 0;
+            const ready = report.status === 200;
             cached = { at: Date.now(), ready, body: {
                     status: ready ? 'ready' : 'not_ready',
-                    checks: { database, magnus: agents.magnus, hivemem, agents: { status: agents.available > 0 ? 'ok' : 'unavailable', available: agents.available } },
+                    checks: {
+                        database: toCheck(checks['database']),
+                        magnus: toCheck(checks['magnus'], 300),
+                        hivemem: toCheck(checks['hivemem']),
+                        agents: { status: agents?.status === 'up' ? 'ok' : 'unavailable', available },
+                    },
                 } };
         }
         c.header('cache-control', 'no-store');

package/dist/server/routes/projects.js

@@ -27,6 +27,11 @@ export function projectRoutes(register, deps) {
             const needing = store.summaries.needingReview();
             projects = projects.filter(project => needing.has(project.id) === (filter.needs_review === 'true'));
         }
+        if (filter.agentRef !== undefined) {
+            // Narrows the list the caller can already read; it never adds a project.
+            const bound = store.team.projectsForAgent(filter.agentRef);
+            projects = projects.filter(project => bound.has(project.id));
+        }
         return { body: { projects: projects.map(summary) } };
     });
     register('POST', '/projects', (_c, { body, principal, idempotencyKey }) => {

package/dist/server/routes/stream.js

@@ -1,5 +1,5 @@
 import { streamSSE } from 'hono/streaming';
-import { STREAM_RECHECK_MS } from '../../auth/oathweave.js';
+import { STREAM_RECHECK_MS } from '../../auth/authenticator.js';
 import { requireProject } from '../deps.js';
 import { bearerToken } from '../routing.js';
 export const HEARTBEAT_MS = 15_000;

package/dist/server/routing.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Hono } from 'hono';
-import { type Authenticator, type Principal } from '../auth/oathweave.js';
+import { type Authenticator, type Principal } from '../auth/authenticator.js';
 import type { Store } from '../db/store.js';
 import { type ArdentStudioBrowserRoute } from '../shared/browser.js';
 import type { AppEnv } from './env.js';

package/dist/server/routing.js

@@ -1,7 +1,7 @@
 // Every route is registered from its entry in the browser contract, so the permissions,
 // idempotency rule, query and body schemas the contract publishes are the ones enforced.
 import { createHash } from 'node:crypto';
-import { AccessDenied } from '../auth/oathweave.js';
+import { AccessDenied } from '../auth/authenticator.js';
 import { ARDENT_STUDIO_API_PREFIX, ardentStudioBrowserRoutes, IDEMPOTENCY_HEADER, idempotencyKeySchema } from '../shared/browser.js';
 import { ApiError } from './errors.js';
 export const JSON_BODY_LIMIT = 1024 * 1024;

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import { type ServerType } from '@hono/node-server';
-import { type Authenticator } from './auth/oathweave.js';
+import { type Authenticator } from './auth/authenticator.js';
 import { ChatterMostClient } from './clients/chattermost.js';
 import { HiveMemClient } from './clients/hivemem.js';
 import { MagnusClient } from './clients/magnus.js';

package/dist/service.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { serve } from '@hono/node-server';
 import { AgentDirectory } from './agents/directory.js';
 import { OperationRelay } from './agents/operations.js';
-import { createAuthenticator, createOathweaveVerifier } from './auth/oathweave.js';
+import { createAuthenticator, createOathweaveVerifier } from './auth/authenticator.js';
 import { BlobStore } from './blobs/store.js';
 import { ChatterMostClient } from './clients/chattermost.js';
 import { HiveMemClient } from './clients/hivemem.js';

package/dist/shared/browser.d.ts

@@ -337,6 +337,7 @@ export declare const listProjectsQuerySchema: z.ZodObject<{
         true: "true";
         false: "false";
     }>>;
+    agentRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const listProjectsResponseSchema: z.ZodObject<{
     projects: z.ZodArray<z.ZodObject<{

package/dist/shared/browser.js

@@ -149,6 +149,8 @@ export const listProjectsQuerySchema = z.object({
     q: z.string().trim().max(200).optional(),
     /** true: only projects with review_pending > 0. */
     needs_review: z.enum(['true', 'false']).optional(),
+    /** Only projects where this agent (<magnusNodeId>~<profile>) is bound to a role in the published or the draft team. */
+    agentRef: agentRefSchema.optional(),
 });
 export const listProjectsResponseSchema = z.object({ projects: z.array(projectSummarySchema) });
 export const projectResponseSchema = projectSchema;
@@ -1222,7 +1224,7 @@ export const ardentStudioBrowserRoutes = [
     { method: 'GET', path: '/health/live', response: liveResponseSchema, permissions: [], idempotent: false },
     { method: 'GET', path: '/health/ready', response: readyResponseSchema, permissions: [], idempotent: false, note: 'Answers 503 with the same body when not ready. Checks are cached for 10 seconds.' },
     // Projects
-    { method: 'GET', path: '/projects', query: listProjectsQuerySchema, response: listProjectsResponseSchema, permissions: READ, idempotent: false, note: 'q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0.' },
+    { method: 'GET', path: '/projects', query: listProjectsQuerySchema, response: listProjectsResponseSchema, permissions: READ, idempotent: false, note: 'q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0. agentRef keeps projects where that agent is bound to a role in the published or the draft team; an agent with no roles gets an empty list. 400 VALIDATION_ERROR for a malformed agentRef.' },
     { method: 'POST', path: '/projects', requestBody: 'json', request: createProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Creates the project HiveMem workspace; when HiveMem is unavailable hivemem.state stays pending and is retried.' },
     { method: 'GET', path: '/projects/{projectId}', response: projectResponseSchema, permissions: READ, idempotent: false },
     { method: 'PATCH', path: '/projects/{projectId}', requestBody: 'json', request: updateProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, note: 'An archived project is read-only (409) except last_area.' },

package/docs/openapi-browser.json

@@ -97,6 +97,15 @@
                 "false"
               ]
             }
+          },
+          {
+            "in": "query",
+            "name": "agentRef",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9._-]{1,128}~[A-Za-z0-9._-]{1,128}$"
+            }
           }
         ],
         "responses": {
@@ -130,7 +139,7 @@
           "ardentstudio:projects:read"
         ],
         "x-idempotent": false,
-        "description": "q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0.",
+        "description": "q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0. agentRef keeps projects where that agent is bound to a role in the published or the draft team; an agent with no roles gets an empty list. 400 VALIDATION_ERROR for a malformed agentRef.",
         "security": [
           {
             "oathweave": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/ardent-studio",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Ardent Project Studio service: projects, team assignment, conversation room and deliverable review for Ardent agents managed by Magnus",
   "keywords": [
     "ardent",
@@ -38,7 +38,7 @@
     }
   },
   "engines": {
-    "node": "^24.22.1 || ^26.13.0"
+    "node": "^24.22.3 || ^26.13.1"
   },
   "publishConfig": {
     "access": "public"
@@ -67,15 +67,17 @@
     "verify": "npm run privacy:test && npm run scan:secrets && npm run check:private && npm run typecheck && npm run lint && npm test && npm run build && npm run check:contracts && npm run pack:check"
   },
   "dependencies": {
+    "@hivemagnus/hive-common": "^0.1.0",
+    "@hivemagnus/hivemem-sdk": "1.1.0",
     "@hivemagnus/magnus-contracts": "2.2.0",
     "@hono/node-server": "^2.1.5",
+    "@photostructure/sqlite": "3.3.1",
     "fflate": "^0.8.3",
-    "hono": "^4.13.17",
+    "hono": "^4.13.18",
     "jose": "^6.2.15",
     "pdfjs-dist": "^6.5.438",
     "yaml": "2.9.1",
-    "zod": "^4.6.7",
-    "@photostructure/sqlite": "3.3.1"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@apidevtools/swagger-parser": "^13.1.0",

package/dist/auth/oathweave.js

@@ -1,123 +0,0 @@
-// Oathweave resource-token verification for ArdentStudio, following the suite pattern
-// (Magnus and HiveMem): RS256 only, exact issuer and audience, at most fifteen minutes,
-// USER actor with a session, and an online session check through userinfo. Failure is closed.
-import { createHash } from 'node:crypto';
-import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
-import { ARDENT_STUDIO_AUDIENCE } from '../shared/browser.js';
-import { effectivePermissions, linkFor } from './links.js';
-/** The token is valid but its subject has no explicit link, so the person has no Studio access. */
-export class AccessDenied extends Error {
-    name = 'AccessDenied';
-}
-/** How long a userinfo answer is reused, measured from when the request started. */
-export const SESSION_CACHE_TTL_MS = 10_000;
-/** How often an open stream re-checks its token. */
-export const STREAM_RECHECK_MS = 5_000;
-const FAILED_CHECK_TTL_MS = 2_000;
-const SESSION_CACHE_MAX = 5_000;
-const REQUEST_TIMEOUT_MS = 3_000;
-export function isHttpsEndpoint(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && !url.username && !url.password && !url.hash;
-    }
-    catch {
-        return false;
-    }
-}
-export function createOathweaveVerifier(options, overrides = {}) {
-    for (const value of [options.issuer, options.jwksUrl, options.userinfoUrl]) {
-        if (!isHttpsEndpoint(value))
-            throw new Error('Oathweave endpoints require verified HTTPS');
-    }
-    const audience = options.audience ?? ARDENT_STUDIO_AUDIENCE;
-    const request = overrides.fetch ?? ((input, init) => fetch(input, init));
-    const now = overrides.now ?? (() => Date.now());
-    const keys = overrides.keys ?? createRemoteJWKSet(new URL(options.jwksUrl), {
-        [customFetch]: (url, init) => request(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) }),
-    });
-    // Holds only tokens whose signature verified, so garbage can neither fill it nor reach userinfo.
-    const sessions = new Map();
-    async function fetchDisplayName(token, subject) {
-        const result = await request(options.userinfoUrl, {
-            headers: { Authorization: `Bearer ${token}` },
-            redirect: 'error',
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-        if (!result.ok)
-            throw new Error('Identity session is inactive');
-        const user = await result.json();
-        if (!user || typeof user !== 'object' || user.sub !== subject)
-            throw new Error('Identity subject mismatch');
-        return 'name' in user && typeof user.name === 'string' && user.name ? user.name : subject;
-    }
-    function sessionCheck(token, subject) {
-        const key = createHash('sha256').update(token).digest('hex');
-        const startedAt = now();
-        const current = sessions.get(key);
-        if (current && startedAt < current.expiresAt)
-            return current.displayName;
-        sessions.delete(key);
-        if (sessions.size >= SESSION_CACHE_MAX) {
-            for (const [entryKey, entry] of sessions)
-                if (entry.expiresAt <= startedAt)
-                    sessions.delete(entryKey);
-            if (sessions.size >= SESSION_CACHE_MAX)
-                sessions.delete(sessions.keys().next().value);
-        }
-        const check = { expiresAt: startedAt + SESSION_CACHE_TTL_MS, displayName: fetchDisplayName(token, subject) };
-        check.displayName.catch(() => { check.expiresAt = Math.min(check.expiresAt, now() + FAILED_CHECK_TTL_MS); });
-        sessions.set(key, check);
-        return check.displayName;
-    }
-    return async (token) => {
-        const { payload } = await jwtVerify(token, keys, {
-            algorithms: ['RS256'],
-            issuer: options.issuer,
-            audience,
-            requiredClaims: ['sub', 'iat', 'exp', 'jti'],
-            maxTokenAge: '15m',
-            currentDate: new Date(now()),
-        });
-        if (payload.aud !== audience || typeof payload.iat !== 'number' || typeof payload.exp !== 'number'
-            || payload.exp <= payload.iat || payload.exp - payload.iat > 900) {
-            throw new Error('Invalid resource token audience or lifetime');
-        }
-        const claims = payload;
-        if (claims['actorType'] !== 'USER'
-            || typeof payload.sub !== 'string' || !payload.sub
-            || typeof payload.jti !== 'string' || !payload.jti
-            || typeof claims['sessionId'] !== 'string' || !claims['sessionId']
-            || typeof claims['clientId'] !== 'string'
-            || !Array.isArray(claims['permissions']) || !claims['permissions'].every(value => typeof value === 'string')) {
-            throw new Error('Invalid resource identity');
-        }
-        const displayName = await sessionCheck(token, payload.sub);
-        return {
-            subject: payload.sub,
-            issuer: options.issuer,
-            sessionId: claims['sessionId'],
-            permissions: claims['permissions'],
-            displayName,
-            issuedAt: payload.iat,
-            expiresAt: payload.exp,
-        };
-    };
-}
-/** Verify a bearer token and map it through its one explicit identity link. */
-export function createAuthenticator(verify, links) {
-    return async (token) => {
-        const identity = await verify(token);
-        const link = linkFor(links, identity.issuer, identity.subject);
-        if (!link)
-            throw new AccessDenied('An explicit unique account link is required');
-        return {
-            userId: link.localUserId,
-            subject: identity.subject,
-            issuer: identity.issuer,
-            displayName: link.displayName ?? identity.displayName,
-            permissions: effectivePermissions(link, identity.permissions),
-            expiresAt: identity.expiresAt,
-        };
-    };
-}