@hivemagnus/ardent-studio 0.3.0 → 0.4.0

package/README.md

@@ -80,6 +80,7 @@ when a required setting is missing or unsafe.
 | `OATHWEAVE_ISSUER` | yes | | Oathweave browser issuer (HTTPS). |
 | `OATHWEAVE_JWKS_URL` | yes | | Oathweave JWKS (HTTPS). |
 | `OATHWEAVE_USERINFO_URL` | yes | | Oathweave userinfo (HTTPS), for session revocation. |
+| `OATHWEAVE_NATIVE_ISSUERS` | no | | Comma-separated Oathweave native issuer ids (its `JWT_ISSUER`). Service tokens they sign are accepted on the audit export only. |
 | `ARDENT_STUDIO_OATHWEAVE_IDENTITIES_JSON` | yes | | Explicit account links; see [docs/OATHWEAVE.md](docs/OATHWEAVE.md). |
 | `ARDENT_STUDIO_OATHWEAVE_TOKEN_URL` | yes | | Oathweave token endpoint for `client_credentials`. |
 | `ARDENT_STUDIO_MAGNUS_URL` | yes | | Magnus control API origin. |
@@ -104,6 +105,12 @@ permission, except the health routes. Every mutation takes `x-idempotency-key`.
 [`src/shared/browser.ts`](src/shared/browser.ts) (also exported as
 `@hivemagnus/ardent-studio/browser`).
 
+`GET /api/ardentstudio/v1/audit/export` serves the audit log as suite `HiveAuditRecord` v1
+records for a collector such as Cindertrace. It needs the permission `ardentstudio:audit:read`,
+which an Oathweave service (client_credentials) token for the audience `ardentstudio` may carry,
+or a linked Studio admin (`ardentstudio:agents:admin`). See
+[docs/OATHWEAVE.md](docs/OATHWEAVE.md#audit-export).
+
 ## Container image
 
 ```bash

package/dist/audit/export.d.ts

@@ -0,0 +1,22 @@
+import type { AuditEntry, AuditRepository } from '../db/repos/audit.js';
+import { type HiveAuditRecord } from '../shared/browser.js';
+export declare const AUDIT_EXPORT_DEFAULT_LIMIT = 100;
+export declare const AUDIT_EXPORT_MAX_LIMIT = 200;
+export declare const AUDIT_DETAILS_MAX_BYTES = 4096;
+type Scalar = string | number | boolean | null;
+export interface AuditExportPage {
+    data: HiveAuditRecord[];
+    nextCursor: string | null;
+}
+/** The numeric id after a cursor; 0 for the first page. Throws a 400 HiveError for a malformed cursor. */
+export declare function cursorPosition(after: string | undefined): number;
+/** Flat scalars only: arrays of scalars are joined, other arrays become a count, objects are dropped. */
+export declare function flattenDetails(detail: Record<string, unknown>): Record<string, Scalar>;
+export declare function toAuditRecord(entry: AuditEntry, taskRefs?: Map<string, string>): HiveAuditRecord;
+/**
+ * One export page for `?after=&limit=`. Throws a 400 HiveError for a malformed query.
+ * `nextCursor` is the last record's cursor whenever the page has records, even when it is the
+ * last page, so a collector can store it and poll again; it is null only for an empty page.
+ */
+export declare function exportAuditPage(audit: AuditRepository, query: URLSearchParams | Readonly<Record<string, string | undefined>>): AuditExportPage;
+export {};

package/dist/audit/export.js

@@ -0,0 +1,115 @@
+// The suite audit export: Studio's append-only audit table as HiveAuditRecord v1, oldest first,
+// keyset-paged on the table's monotonic id. Details are flattened to scalars, redacted with the
+// suite's log redaction and capped at 4 KB; they never hold secrets or file contents.
+import { decodeCursor, encodeCursor, parseFeedQuery } from '@hivemagnus/hive-common/events';
+import { HiveError } from '@hivemagnus/hive-common/errors';
+import { redact } from '@hivemagnus/hive-common/log';
+import { agentRefSchema } from '../shared/browser.js';
+export const AUDIT_EXPORT_DEFAULT_LIMIT = 100;
+export const AUDIT_EXPORT_MAX_LIMIT = 200;
+export const AUDIT_DETAILS_MAX_BYTES = 4096;
+const MAX_STRING = 512;
+/** Detail keys that could carry content rather than metadata. None are recorded today; this keeps it so. */
+const CONTENT_KEYS = new Set(['body', 'body_md', 'content', 'text', 'prompt', 'brief', 'soul', 'identity', 'instructions', 'answer', 'message']);
+/** The numeric id after a cursor; 0 for the first page. Throws a 400 HiveError for a malformed cursor. */
+export function cursorPosition(after) {
+    if (after === undefined || after === '')
+        return 0;
+    const position = decodeCursor(after);
+    const id = position.id;
+    if (Object.keys(position).length !== 1 || typeof id !== 'number' || !Number.isSafeInteger(id) || id < 0) {
+        throw new HiveError('invalid_cursor', 'The cursor is not valid', { status: 400 });
+    }
+    return id;
+}
+function scalar(value) {
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string')
+        return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…` : value;
+    return undefined;
+}
+/** Flat scalars only: arrays of scalars are joined, other arrays become a count, objects are dropped. */
+export function flattenDetails(detail) {
+    const redacted = redact(detail);
+    const flat = {};
+    for (const [key, value] of Object.entries(redacted)) {
+        if (CONTENT_KEYS.has(key.toLowerCase()))
+            continue;
+        const direct = scalar(value);
+        if (direct !== undefined) {
+            flat[key] = direct;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            const items = value.map(item => scalar(item));
+            if (items.every(item => item !== undefined && item !== null && typeof item !== 'boolean')) {
+                const joined = scalar(items.join(','));
+                if (joined !== undefined)
+                    flat[key] = joined;
+            }
+            else
+                flat[`${key}_count`] = value.length;
+        }
+    }
+    // Keep the record bounded: drop the longest values until the details fit.
+    while (Buffer.byteLength(JSON.stringify(flat)) > AUDIT_DETAILS_MAX_BYTES) {
+        const longest = Object.entries(flat).sort(([, a], [, b]) => JSON.stringify(b).length - JSON.stringify(a).length)[0];
+        if (!longest)
+            break;
+        delete flat[longest[0]];
+        flat.truncated = true;
+    }
+    return flat;
+}
+function actorOf(entry) {
+    const userId = entry.actor_user_id;
+    if (userId === 'system')
+        return { type: 'system', id: 'system' };
+    if (userId.startsWith('service:')) {
+        return { type: 'service', id: entry.actor_subject ?? userId.slice('service:'.length), ...(entry.actor_issuer ? { issuer: entry.actor_issuer } : {}) };
+    }
+    return {
+        type: 'user',
+        id: entry.actor_subject ?? userId,
+        ...(entry.actor_issuer ? { issuer: entry.actor_issuer } : {}),
+        displayName: userId,
+    };
+}
+/** The agent a record is about: an agent target, a task that ran on an agent, or a detail agent_ref. */
+function agentRefOf(entry, taskRefs) {
+    const candidates = [
+        entry.target_type === 'agent' ? entry.target_id : undefined,
+        entry.target_type === 'task' ? taskRefs.get(entry.target_id) : undefined,
+        typeof entry.detail.agent_ref === 'string' ? entry.detail.agent_ref : undefined,
+    ];
+    return candidates.find(candidate => candidate !== undefined && agentRefSchema.safeParse(candidate).success);
+}
+export function toAuditRecord(entry, taskRefs = new Map()) {
+    const agentRef = agentRefOf(entry, taskRefs);
+    return {
+        id: `ardentstudio:audit:${entry.id}`,
+        product: 'ardentstudio',
+        occurredAt: new Date(entry.at).toISOString(),
+        action: entry.action.toLowerCase(),
+        outcome: 'success',
+        actor: actorOf(entry),
+        ...(entry.target_type || entry.target_id ? { target: { ...(entry.target_type ? { type: entry.target_type } : {}), ...(entry.target_id ? { id: entry.target_id } : {}) } } : {}),
+        ...(agentRef ? { subject: { agentRef, nodeId: agentRef.slice(0, agentRef.indexOf('~')) } } : {}),
+        details: flattenDetails(entry.detail),
+    };
+}
+/**
+ * One export page for `?after=&limit=`. Throws a 400 HiveError for a malformed query.
+ * `nextCursor` is the last record's cursor whenever the page has records, even when it is the
+ * last page, so a collector can store it and poll again; it is null only for an empty page.
+ */
+export function exportAuditPage(audit, query) {
+    const { after, limit } = parseFeedQuery(query, { defaultLimit: AUDIT_EXPORT_DEFAULT_LIMIT, maxLimit: AUDIT_EXPORT_MAX_LIMIT });
+    const entries = audit.listAfter(cursorPosition(after), limit);
+    const taskRefs = audit.taskAgentRefs(entries.filter(entry => entry.target_type === 'task').map(entry => entry.target_id));
+    const last = entries.at(-1);
+    return { data: entries.map(entry => toAuditRecord(entry, taskRefs)), nextCursor: last ? encodeCursor({ id: last.id }) : null };
+}

package/dist/auth/authenticator.d.ts

@@ -6,8 +6,14 @@ export interface OathweaveOptions {
     jwksUrl: string;
     userinfoUrl: string;
     audience?: string;
+    /**
+     * Oathweave native issuer identifiers (its JWT issuer name, for example `hive-iam`). Accepted
+     * for service tokens only, so only on routes that accept services (the audit export).
+     */
+    nativeIssuers?: readonly string[];
 }
 export interface OathweaveIdentity {
+    kind: 'user' | 'service';
     subject: string;
     issuer: string;
     sessionId: string;
@@ -16,9 +22,18 @@ export interface OathweaveIdentity {
     issuedAt: number;
     expiresAt: number;
 }
-export type OathweaveVerifier = (token: string) => Promise<OathweaveIdentity>;
-/** A verified, linked caller. */
+export interface VerifyOptions {
+    /** `any` also accepts service (client-credentials) tokens. The default is people only. */
+    accept?: 'user' | 'any';
+}
+export type OathweaveVerifier = (token: string, options?: VerifyOptions) => Promise<OathweaveIdentity>;
+/** The only permissions a service token can carry into Studio. */
+export declare const SERVICE_PERMISSIONS: readonly ArdentStudioPermission[];
+/** A verified, linked caller, or a verified service on a route that accepts services. */
 export interface Principal {
+    /** Absent means a person, as before services were accepted anywhere. */
+    kind?: 'user' | 'service';
+    /** The linked Studio user, or `service:<client id>` for a service. */
     userId: string;
     subject: string;
     issuer: string;
@@ -49,6 +64,9 @@ export declare function createOathweaveVerifier(options: OathweaveOptions, overr
     fetch?: typeof fetch;
     now?: () => number;
 }): OathweaveVerifier;
-export type Authenticator = (token: string) => Promise<Principal>;
-/** Verify a bearer token and map it through its one explicit identity link. */
+export type Authenticator = (token: string, options?: VerifyOptions) => Promise<Principal>;
+/**
+ * Verify a bearer token and map a person through their one explicit identity link. A service
+ * (only with `accept: 'any'`) needs no link and keeps only SERVICE_PERMISSIONS.
+ */
 export declare function createAuthenticator(verify: OathweaveVerifier, links: readonly IdentityLink[]): Authenticator;

package/dist/auth/authenticator.js

@@ -1,10 +1,13 @@
 // 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.
+// Failure is closed. Studio accepts people only; service tokens are refused everywhere except on
+// routes that opt in (the audit export), where a service gets only SERVICE_PERMISSIONS.
 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 only permissions a service token can carry into Studio. */
+export const SERVICE_PERMISSIONS = ['ardentstudio:audit:read'];
 /** 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';
@@ -28,33 +31,52 @@ export function createOathweaveVerifier(options, overrides = {}) {
         audience: options.audience ?? ARDENT_STUDIO_AUDIENCE,
         jwksUrl: options.jwksUrl,
         userinfoUrl: options.userinfoUrl,
+        ...(options.nativeIssuers?.length ? { nativeIssuers: options.nativeIssuers, nativeIssuerAccept: 'service' } : {}),
         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 async (token, verifyOptions = {}) => {
+        const principal = verifyOptions.accept === 'any' ? await verifier.verify(token, { accept: 'any' }) : await verifier.verifyUser(token);
         return {
+            kind: principal.kind,
             subject: principal.subject,
             issuer: principal.issuer,
-            sessionId: principal.sessionId,
+            sessionId: principal.kind === 'user' ? principal.sessionId : '',
             permissions: [...principal.permissions],
-            displayName: principal.displayName,
+            displayName: principal.kind === 'user' ? principal.displayName : principal.subject,
             issuedAt: principal.issuedAt,
             expiresAt: principal.expiresAt,
         };
     };
 }
-/** Verify a bearer token and map it through its one explicit identity link. */
+/**
+ * Verify a bearer token and map a person through their one explicit identity link. A service
+ * (only with `accept: 'any'`) needs no link and keeps only SERVICE_PERMISSIONS.
+ */
 export function createAuthenticator(verify, links) {
-    return async (token) => {
-        const identity = await verify(token);
+    return async (token, options = {}) => {
+        const identity = await verify(token, options);
+        if (identity.kind === 'service') {
+            if (options.accept !== 'any')
+                throw new Error('Service tokens are not accepted here');
+            return {
+                kind: 'service',
+                userId: `service:${identity.subject}`,
+                subject: identity.subject,
+                issuer: identity.issuer,
+                displayName: identity.subject,
+                permissions: SERVICE_PERMISSIONS.filter(permission => identity.permissions.includes(permission)),
+                expiresAt: identity.expiresAt,
+            };
+        }
         const link = linkFor(links, identity.issuer, identity.subject);
         if (!link)
             throw new AccessDenied('An explicit unique account link is required');
         return {
+            kind: 'user',
             userId: link.localUserId,
             subject: identity.subject,
             issuer: identity.issuer,

package/dist/auth/links.d.ts

@@ -15,6 +15,7 @@ declare const linkSchema: z.ZodObject<{
         "ardentstudio:templates:write": "ardentstudio:templates:write";
         "ardentstudio:review:write": "ardentstudio:review:write";
         "ardentstudio:agents:admin": "ardentstudio:agents:admin";
+        "ardentstudio:audit:read": "ardentstudio:audit:read";
     }>>>;
 }, z.core.$strict>;
 export type IdentityLink = z.infer<typeof linkSchema>;

package/dist/config.d.ts

@@ -22,6 +22,8 @@ export interface Config {
         userinfoUrl: string;
         tokenUrl: string;
         identities: IdentityLink[];
+        /** OATHWEAVE_NATIVE_ISSUERS: native issuer ids accepted for service tokens on the audit export. */
+        nativeIssuers: string[];
     };
     magnus: ServiceClientConfig;
     hivemem: ServiceClientConfig;

package/dist/config.js

@@ -1,5 +1,6 @@
 import { isAbsolute, resolve } from 'node:path';
 import { z } from 'zod';
+import { OATHWEAVE_NATIVE_ISSUER_PATTERN } from '@hivemagnus/hive-common/oathweave';
 import { parseIdentityLinks } from './auth/links.js';
 import { trimTrailingSlashes } from './url.js';
 export const DEFAULT_PORT = 8097;
@@ -24,6 +25,7 @@ export const ENV_CATALOG = [
     { name: 'OATHWEAVE_ISSUER', required: true, secret: false, description: 'Oathweave browser issuer (HTTPS).' },
     { name: 'OATHWEAVE_JWKS_URL', required: true, secret: false, description: 'Oathweave JWKS URL (HTTPS).' },
     { name: 'OATHWEAVE_USERINFO_URL', required: true, secret: false, description: 'Oathweave userinfo URL (HTTPS), used for online session revocation.' },
+    { name: 'OATHWEAVE_NATIVE_ISSUERS', required: false, secret: false, description: 'Optional comma-separated Oathweave native issuer ids (its JWT issuer name). Service tokens they sign are accepted on the audit export only; never for people.' },
     { name: 'ARDENT_STUDIO_OATHWEAVE_IDENTITIES_JSON', required: true, secret: false, description: 'JSON array of explicit account links: [{issuer, subject, localUserId, displayName?, permissions?}].' },
     { name: 'ARDENT_STUDIO_OATHWEAVE_TOKEN_URL', required: true, secret: false, description: 'Oathweave OAuth token endpoint for the client_credentials grant.' },
     { name: 'ARDENT_STUDIO_MAGNUS_URL', required: true, secret: false, description: 'Magnus control API base URL (the origin that serves /api/v1).' },
@@ -105,6 +107,10 @@ export function loadConfig(env = process.env) {
     const jwksUrl = url('OATHWEAVE_JWKS_URL', true);
     const userinfoUrl = url('OATHWEAVE_USERINFO_URL', true);
     const tokenUrl = url('ARDENT_STUDIO_OATHWEAVE_TOKEN_URL', false);
+    const nativeIssuers = (value('OATHWEAVE_NATIVE_ISSUERS') ?? '').split(',').map(item => item.trim()).filter(Boolean);
+    if (nativeIssuers.some(item => !OATHWEAVE_NATIVE_ISSUER_PATTERN.test(item))) {
+        issues.push({ name: 'OATHWEAVE_NATIVE_ISSUERS', message: 'must be comma-separated Oathweave native issuer ids ([a-z][a-z0-9-], at most 64 each)' });
+    }
     let identities = [];
     const identitiesRaw = required('ARDENT_STUDIO_OATHWEAVE_IDENTITIES_JSON');
     if (identitiesRaw) {
@@ -152,7 +158,7 @@ export function loadConfig(env = process.env) {
         maxBlobBytes: numeric('ARDENT_STUDIO_MAX_BLOB_BYTES', DEFAULT_MAX_BLOB_BYTES, 1024, 1024 * 1024 * 1024),
         eventRetentionDays: numeric('ARDENT_STUDIO_EVENT_RETENTION_DAYS', DEFAULT_EVENT_RETENTION_DAYS, 1, 3650),
         logLevel: logLevel,
-        oathweave: { issuer, jwksUrl, userinfoUrl, tokenUrl, identities },
+        oathweave: { issuer, jwksUrl, userinfoUrl, tokenUrl, identities, nativeIssuers },
         magnus,
         hivemem,
         chattermost,

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

@@ -34,4 +34,8 @@ export declare class AuditRepository {
         targetId?: string;
         limit?: number;
     }): AuditEntry[];
+    /** Oldest first, strictly after `afterId`. The id is the table's monotonic key, so pages never skip or repeat. */
+    listAfter(afterId: number, limit: number): AuditEntry[];
+    /** The Ardent agent each task ran on, for the tasks that have one. */
+    taskAgentRefs(taskIds: readonly string[]): Map<string, string>;
 }

package/dist/db/repos/audit.js

@@ -17,4 +17,20 @@ export class AuditRepository {
             : this.db.prepare('SELECT * FROM audit ORDER BY id DESC LIMIT ?').all(filter.limit ?? 100));
         return rows.map(({ detail_json, ...row }) => ({ ...row, detail: readJson(detail_json, {}) }));
     }
+    /** Oldest first, strictly after `afterId`. The id is the table's monotonic key, so pages never skip or repeat. */
+    listAfter(afterId, limit) {
+        const rows = this.db.prepare('SELECT * FROM audit WHERE id > ? ORDER BY id ASC LIMIT ?').all(afterId, limit);
+        return rows.map(({ detail_json, ...row }) => ({ ...row, detail: readJson(detail_json, {}) }));
+    }
+    /** The Ardent agent each task ran on, for the tasks that have one. */
+    taskAgentRefs(taskIds) {
+        const refs = new Map();
+        if (!taskIds.length)
+            return refs;
+        const rows = this.db.prepare(`SELECT id, ardent_agent_ref FROM tasks WHERE ardent_agent_ref IS NOT NULL AND id IN (${taskIds.map(() => '?').join(', ')})`)
+            .all(...taskIds);
+        for (const row of rows)
+            refs.set(row.id, row.ardent_agent_ref);
+        return refs;
+    }
 }

package/dist/server/app.js

@@ -3,6 +3,7 @@ import { Hono } from 'hono';
 import { ARDENT_STUDIO_API_PREFIX } from '../shared/browser.js';
 import { errorResponse } from './errors.js';
 import { createRouter } from './routing.js';
+import { auditRoutes } from './routes/audit.js';
 import { agentStudioRoutes } from './routes/agent-studio.js';
 import { agentRoutes } from './routes/agents.js';
 import { fileRoutes } from './routes/files.js';
@@ -43,6 +44,7 @@ export function createApp(deps) {
     roomRoutes(register, deps);
     workRoutes(register, deps);
     reviewRoutes(register, deps);
+    auditRoutes(register, deps);
     streamRoutes(register, deps);
     return app;
 }

package/dist/server/errors.js

@@ -1,3 +1,4 @@
+import { HiveError } from '@hivemagnus/hive-common/errors';
 import { ZodError } from 'zod';
 export class ApiError extends Error {
     status;
@@ -17,6 +18,10 @@ export function errorResponse(c, error, logger) {
     if (error instanceof ApiError) {
         return c.json({ error: { code: error.code, message: error.message, ...(error.details !== undefined ? { details: error.details } : {}) } }, error.status);
     }
+    if (HiveError.is(error) && error.status === 400) {
+        // hive-common feed helpers: a malformed cursor or limit.
+        return c.json({ error: { code: 'VALIDATION_ERROR', message: error.message } }, 400);
+    }
     if (error instanceof ZodError) {
         return c.json({ error: { code: 'VALIDATION_ERROR', message: 'The request is invalid', details: error.issues.map(issue => ({ path: issue.path.join('.'), message: issue.message })) } }, 400);
     }

package/dist/server/routes/audit.d.ts

@@ -0,0 +1,3 @@
+import type { AppDeps } from '../deps.js';
+import type { createRouter } from '../routing.js';
+export declare function auditRoutes(register: ReturnType<typeof createRouter>, deps: AppDeps): void;

package/dist/server/routes/audit.js

@@ -0,0 +1,6 @@
+// The suite audit export (HiveAuditRecord v1). Read by Cindertrace with an Oathweave service
+// token holding ardentstudio:audit:read, or by a linked Studio admin.
+import { exportAuditPage } from '../../audit/export.js';
+export function auditRoutes(register, deps) {
+    register('GET', '/audit/export', c => ({ body: exportAuditPage(deps.store.audit, new URL(c.req.url).searchParams) }));
+}

package/dist/server/routing.d.ts

@@ -22,7 +22,10 @@ export declare function routeDefinition(method: ArdentStudioBrowserRoute['method
 /** `/projects/{projectId}` → `/projects/:projectId` */
 export declare function honoPath(path: string): string;
 export declare function bearerToken(c: Context): string | undefined;
-export declare function authenticateRequest(c: Context, authenticate: Authenticator, permissions: readonly string[]): Promise<Principal>;
+export declare function authenticateRequest(c: Context, authenticate: Authenticator, permissions: readonly string[], options?: {
+    accept?: 'user' | 'any';
+    orPermission?: string | undefined;
+}): Promise<Principal>;
 export declare function createRouter(app: Hono<AppEnv>, deps: {
     store: Store;
     authenticate: Authenticator;

package/dist/server/routing.js

@@ -20,21 +20,24 @@ export function bearerToken(c) {
     const match = header ? /^Bearer ([A-Za-z0-9._~+/-]+=*)$/.exec(header) : null;
     return match?.[1];
 }
-export async function authenticateRequest(c, authenticate, permissions) {
+export async function authenticateRequest(c, authenticate, permissions, options = {}) {
     const token = bearerToken(c);
     if (!token)
         throw new ApiError(401, 'UNAUTHENTICATED', 'A bearer token is required');
     let principal;
     try {
-        principal = await authenticate(token);
+        principal = await authenticate(token, options.accept === 'any' ? { accept: 'any' } : {});
     }
     catch (error) {
         if (error instanceof AccessDenied)
             throw new ApiError(403, 'NO_ACCOUNT_LINK', 'This identity has no Ardent Project Studio account link');
         throw new ApiError(401, 'UNAUTHENTICATED', 'The bearer token is not valid');
     }
-    const missing = permissions.filter(permission => !principal.permissions.includes(permission));
-    if (missing.length)
+    const holds = (permission) => principal.permissions.includes(permission);
+    const missing = permissions.filter(permission => !holds(permission));
+    // The alternative is for linked people (admins); a service only ever holds SERVICE_PERMISSIONS.
+    const admitted = principal.kind !== 'service' && options.orPermission !== undefined && holds(options.orPermission);
+    if (missing.length && !admitted)
         throw new ApiError(403, 'FORBIDDEN', 'Missing permission', { missing });
     return principal;
 }
@@ -64,7 +67,7 @@ export function createRouter(app, deps) {
     return function register(method, path, handler) {
         const route = routeDefinition(method, path);
         app.on(method, honoPath(path), async (c) => {
-            const principal = route.permissions.length ? await authenticateRequest(c, deps.authenticate, route.permissions) : undefined;
+            const principal = route.permissions.length ? await authenticateRequest(c, deps.authenticate, route.permissions, { accept: route.accept ?? 'user', orPermission: route.orPermission }) : undefined;
             c.set('principal', principal);
             let idempotencyKey;
             if (route.idempotent) {

package/dist/service.js

@@ -44,7 +44,7 @@ export function createService(config, options = {}) {
     const chattermost = config.chattermost ? new ChatterMostClient(config.chattermost.webhookUrl, options.fetch) : undefined;
     const knowledge = new KnowledgeSync(store, blobs, hivemem, logger);
     const agents = new AgentDirectory(magnus, store);
-    const authenticate = options.authenticate ?? createAuthenticator(createOathweaveVerifier({ issuer: config.oathweave.issuer, jwksUrl: config.oathweave.jwksUrl, userinfoUrl: config.oathweave.userinfoUrl }), config.oathweave.identities);
+    const authenticate = options.authenticate ?? createAuthenticator(createOathweaveVerifier({ issuer: config.oathweave.issuer, jwksUrl: config.oathweave.jwksUrl, userinfoUrl: config.oathweave.userinfoUrl, nativeIssuers: config.oathweave.nativeIssuers }), config.oathweave.identities);
     const live = new LiveText(bus);
     const conductor = new Conductor({ store, blobs, magnus, agents, live, logger });
     const importer = attachReview({ store, blobs, magnus, conductor, logger });

package/dist/shared/browser.d.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 export declare const ardentStudioBrowserContractVersion = 1;
 export declare const ARDENT_STUDIO_API_PREFIX = "/api/ardentstudio/v1";
 export declare const ARDENT_STUDIO_AUDIENCE = "ardentstudio";
-export declare const ARDENT_STUDIO_PERMISSIONS: readonly ["ardentstudio:projects:read", "ardentstudio:projects:write", "ardentstudio:templates:read", "ardentstudio:templates:write", "ardentstudio:review:write", "ardentstudio:agents:admin"];
+export declare const ARDENT_STUDIO_PERMISSIONS: readonly ["ardentstudio:projects:read", "ardentstudio:projects:write", "ardentstudio:templates:read", "ardentstudio:templates:write", "ardentstudio:review:write", "ardentstudio:agents:admin", "ardentstudio:audit:read"];
 export declare const permissionSchema: z.ZodEnum<{
     "ardentstudio:projects:read": "ardentstudio:projects:read";
     "ardentstudio:projects:write": "ardentstudio:projects:write";
@@ -10,6 +10,7 @@ export declare const permissionSchema: z.ZodEnum<{
     "ardentstudio:templates:write": "ardentstudio:templates:write";
     "ardentstudio:review:write": "ardentstudio:review:write";
     "ardentstudio:agents:admin": "ardentstudio:agents:admin";
+    "ardentstudio:audit:read": "ardentstudio:audit:read";
 }>;
 export type ArdentStudioPermission = z.infer<typeof permissionSchema>;
 /** Every mutation sends this header. A repeated key replays the first answer; a different request with the same key is a 409. */
@@ -5803,6 +5804,86 @@ export declare const readyResponseSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const hiveAuditRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    product: z.ZodEnum<{
+        ardentstudio: "ardentstudio";
+        hivemem: "hivemem";
+        hiveskills: "hiveskills";
+        embermend: "embermend";
+    }>;
+    occurredAt: z.ZodISODateTime;
+    action: z.ZodString;
+    outcome: z.ZodEnum<{
+        success: "success";
+        failure: "failure";
+    }>;
+    actor: z.ZodObject<{
+        type: z.ZodEnum<{
+            agent: "agent";
+            user: "user";
+            system: "system";
+            service: "service";
+        }>;
+        id: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    target: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    subject: z.ZodOptional<z.ZodObject<{
+        actorId: z.ZodOptional<z.ZodString>;
+        agentRef: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    details: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>;
+export type HiveAuditRecord = z.infer<typeof hiveAuditRecordSchema>;
+export declare const auditExportQuerySchema: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const auditExportResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        product: z.ZodEnum<{
+            ardentstudio: "ardentstudio";
+            hivemem: "hivemem";
+            hiveskills: "hiveskills";
+            embermend: "embermend";
+        }>;
+        occurredAt: z.ZodISODateTime;
+        action: z.ZodString;
+        outcome: z.ZodEnum<{
+            success: "success";
+            failure: "failure";
+        }>;
+        actor: z.ZodObject<{
+            type: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+                system: "system";
+                service: "service";
+            }>;
+            id: z.ZodString;
+            issuer: z.ZodOptional<z.ZodString>;
+            displayName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        target: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        subject: z.ZodOptional<z.ZodObject<{
+            actorId: z.ZodOptional<z.ZodString>;
+            agentRef: z.ZodOptional<z.ZodString>;
+            nodeId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        details: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 export interface ArdentStudioBrowserRoute {
     method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
     /** Relative to ARDENT_STUDIO_API_PREFIX, with `{name}` for each path parameter. */
@@ -5815,6 +5896,10 @@ export interface ArdentStudioBrowserRoute {
     response: z.ZodType | null;
     /** Every listed permission is required. An empty list means no authentication. */
     permissions: readonly ArdentStudioPermission[];
+    /** A linked person holding this permission passes instead of `permissions` (Studio admins). */
+    orPermission?: ArdentStudioPermission;
+    /** `any` also accepts Oathweave service (client-credentials) tokens; the default is people only. */
+    accept?: 'user' | 'any';
     /** The route requires the x-idempotency-key header. */
     idempotent: boolean;
     successStatus?: 201;

package/dist/shared/browser.js

@@ -15,6 +15,7 @@ export const ARDENT_STUDIO_PERMISSIONS = [
     'ardentstudio:templates:write',
     'ardentstudio:review:write',
     'ardentstudio:agents:admin',
+    'ardentstudio:audit:read',
 ];
 export const permissionSchema = z.enum(ARDENT_STUDIO_PERMISSIONS);
 /** Every mutation sends this header. A repeated key replays the first answer; a different request with the same key is a 409. */
@@ -1213,12 +1214,46 @@ export const readyResponseSchema = z.object({
         agents: z.object({ status: z.enum(['ok', 'unavailable']), available: z.number().int() }),
     }),
 });
+// ── Audit export (HiveAuditRecord v1, shared across the suite) ──
+/** The suite-wide audit record. Every product serves the same shape so one collector can parse them all. */
+const auditScalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const hiveAuditRecordSchema = z.object({
+    id: z.string().regex(/^(hivemem|hiveskills|ardentstudio|embermend):audit:[A-Za-z0-9._:-]{1,200}$/),
+    product: z.enum(['hivemem', 'hiveskills', 'ardentstudio', 'embermend']),
+    occurredAt: z.iso.datetime(),
+    action: z.string().regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/).max(128),
+    outcome: z.enum(['success', 'failure']),
+    actor: z.object({
+        type: z.enum(['user', 'service', 'agent', 'system']),
+        id: z.string().min(1).max(256),
+        issuer: z.string().max(512).optional(),
+        displayName: z.string().max(256).optional(),
+    }).strict(),
+    /** Omitted when empty. */
+    target: z.object({ type: z.string().max(64).optional(), id: z.string().max(256).optional() }).strict().optional(),
+    /** Omitted when empty. */
+    subject: z.object({ actorId: z.string().max(256).optional(), agentRef: z.string().max(257).optional(), nodeId: z.string().max(128).optional() }).strict().optional(),
+    /** Flat scalars, at most 4 KB serialized, already redacted. Never secrets, memory content, prompts or file contents. */
+    details: z.record(z.string(), auditScalarSchema),
+}).strict();
+export const auditExportQuerySchema = z.object({
+    /** The opaque nextCursor of the previous page. Omit for the oldest record. */
+    after: z.string().max(512).optional(),
+    /** 1 to 200; default 100. Larger values are clamped to 200. */
+    limit: z.string().regex(/^\d{1,6}$/).optional(),
+});
+export const auditExportResponseSchema = z.object({
+    data: z.array(hiveAuditRecordSchema),
+    /** The last record's cursor whenever `data` is not empty, even on the last page; null only when `data` is empty (caught up). Send it as `after` to read on. */
+    nextCursor: z.string().nullable(),
+});
 const READ = ['ardentstudio:projects:read'];
 const WRITE = ['ardentstudio:projects:write'];
 const TEMPLATES_READ = ['ardentstudio:templates:read'];
 const TEMPLATES_WRITE = ['ardentstudio:templates:write'];
 const REVIEW = ['ardentstudio:review:write'];
 const AGENTS_ADMIN = ['ardentstudio:agents:admin'];
+const AUDIT_READ = ['ardentstudio:audit:read'];
 export const ardentStudioBrowserRoutes = [
     // Health
     { method: 'GET', path: '/health/live', response: liveResponseSchema, permissions: [], idempotent: false },
@@ -1311,6 +1346,9 @@ export const ardentStudioBrowserRoutes = [
     { method: 'POST', path: '/projects/{projectId}/exports', requestBody: 'json', request: createExportRequestSchema, response: exportResponseSchema, permissions: REVIEW, idempotent: true, successStatus: 201, note: 'A zip of the final revisions with manifest.json (Ardent manifest fields, review status and decisions). Deliverables without a final revision are listed as excluded; none at all answers 409 NOTHING_FINAL.' },
     { method: 'GET', path: '/files/{fileId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
     { method: 'GET', path: '/revisions/{revisionId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
+    // Audit
+    { method: 'GET', path: '/audit/export', query: auditExportQuerySchema, response: auditExportResponseSchema, permissions: AUDIT_READ, orPermission: 'ardentstudio:agents:admin', accept: 'any', idempotent: false,
+        note: 'Every audit record, oldest first, as HiveAuditRecord v1, keyset-paged on the record id. Accepts an Oathweave service token with ardentstudio:audit:read (no account link needed; native-issuer service tokens too when OATHWEAVE_NATIVE_ISSUERS lists the issuer), or a linked person with ardentstudio:audit:read or ardentstudio:agents:admin. 400 for a malformed cursor or limit. nextCursor is the last record\'s cursor whenever data is not empty, and null only when data is empty (caught up).' },
     // Stream
     {
         method: 'GET', path: '/projects/{projectId}/stream', query: streamQuerySchema, response: null, permissions: READ, idempotent: false,

package/docs/openapi-browser.json

@@ -5256,6 +5256,70 @@
         ]
       }
     },
+    "/api/ardentstudio/v1/audit/export": {
+      "get": {
+        "operationId": "getAuditExport",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "after",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "maxLength": 512
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "pattern": "^\\d{1,6}$"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuditExportResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/Error"
+          },
+          "401": {
+            "$ref": "#/components/responses/Error"
+          },
+          "403": {
+            "$ref": "#/components/responses/Error"
+          },
+          "404": {
+            "$ref": "#/components/responses/Error"
+          },
+          "409": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "x-permissions": [
+          "ardentstudio:audit:read"
+        ],
+        "x-idempotent": false,
+        "x-or-permission": "ardentstudio:agents:admin",
+        "x-accept": "any",
+        "description": "Every audit record, oldest first, as HiveAuditRecord v1, keyset-paged on the record id. Accepts an Oathweave service token with ardentstudio:audit:read (no account link needed; native-issuer service tokens too when OATHWEAVE_NATIVE_ISSUERS lists the issuer), or a linked person with ardentstudio:audit:read or ardentstudio:agents:admin. 400 for a malformed cursor or limit. nextCursor is the last record's cursor whenever data is not empty, and null only when data is empty (caught up).",
+        "security": [
+          {
+            "oathweave": []
+          }
+        ]
+      }
+    },
     "/api/ardentstudio/v1/projects/{projectId}/stream": {
       "get": {
         "operationId": "getProjectsProjectIdStream",
@@ -5338,7 +5402,7 @@
         "type": "http",
         "scheme": "bearer",
         "bearerFormat": "JWT",
-        "description": "Oathweave resource token with audience ardentstudio. Permissions: ardentstudio:projects:read, ardentstudio:projects:write, ardentstudio:templates:read, ardentstudio:templates:write, ardentstudio:review:write, ardentstudio:agents:admin."
+        "description": "Oathweave resource token with audience ardentstudio. Permissions: ardentstudio:projects:read, ardentstudio:projects:write, ardentstudio:templates:read, ardentstudio:templates:write, ardentstudio:review:write, ardentstudio:agents:admin, ardentstudio:audit:read."
       }
     },
     "responses": {
@@ -6408,6 +6472,27 @@
           "knowledge"
         ]
       },
+      "AuditExportResponse": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/HiveAuditRecord"
+            }
+          },
+          "nextCursor": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "data",
+          "nextCursor"
+        ]
+      },
       "AvatarPreset": {
         "type": "object",
         "properties": {
@@ -8109,6 +8194,125 @@
           "at"
         ]
       },
+      "HiveAuditRecord": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^(hivemem|hiveskills|ardentstudio|embermend):audit:[A-Za-z0-9._:-]{1,200}$"
+          },
+          "product": {
+            "type": "string",
+            "enum": [
+              "hivemem",
+              "hiveskills",
+              "ardentstudio",
+              "embermend"
+            ]
+          },
+          "occurredAt": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+          },
+          "action": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+          },
+          "outcome": {
+            "type": "string",
+            "enum": [
+              "success",
+              "failure"
+            ]
+          },
+          "actor": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "user",
+                  "service",
+                  "agent",
+                  "system"
+                ]
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256
+              },
+              "issuer": {
+                "type": "string",
+                "maxLength": 512
+              },
+              "displayName": {
+                "type": "string",
+                "maxLength": 256
+              }
+            },
+            "required": [
+              "type",
+              "id"
+            ]
+          },
+          "target": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "maxLength": 64
+              },
+              "id": {
+                "type": "string",
+                "maxLength": 256
+              }
+            }
+          },
+          "subject": {
+            "type": "object",
+            "properties": {
+              "actorId": {
+                "type": "string",
+                "maxLength": 256
+              },
+              "agentRef": {
+                "type": "string",
+                "maxLength": 257
+              },
+              "nodeId": {
+                "type": "string",
+                "maxLength": 128
+              }
+            }
+          },
+          "details": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": [
+                "string",
+                "number",
+                "boolean",
+                "null"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "product",
+          "occurredAt",
+          "action",
+          "outcome",
+          "actor",
+          "details"
+        ]
+      },
       "HivememState": {
         "type": "string",
         "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/ardent-studio",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Ardent Project Studio service: projects, team assignment, conversation room and deliverable review for Ardent agents managed by Magnus",
   "keywords": [
     "ardent",
@@ -67,7 +67,7 @@
     "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/hive-common": "^0.4.0",
     "@hivemagnus/hivemem-sdk": "1.1.0",
     "@hivemagnus/magnus-contracts": "2.2.0",
     "@hono/node-server": "^2.1.5",