@hivemagnus/ardent-studio 0.2.1 → 0.4.0

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": []
@@ -5247,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",
@@ -5329,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": {
@@ -6399,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": {
@@ -8100,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.2.1",
+  "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,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.4.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.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.d.ts

@@ -1,46 +0,0 @@
-import { type JWTVerifyGetKey } from 'jose';
-import { type ArdentStudioPermission } from '../shared/browser.js';
-import { type IdentityLink } from './links.js';
-export interface OathweaveOptions {
-    issuer: string;
-    jwksUrl: string;
-    userinfoUrl: string;
-    audience?: string;
-}
-export interface OathweaveIdentity {
-    subject: string;
-    issuer: string;
-    sessionId: string;
-    permissions: string[];
-    displayName: string;
-    issuedAt: number;
-    expiresAt: number;
-}
-export type OathweaveVerifier = (token: string) => Promise<OathweaveIdentity>;
-/** A verified, linked caller. */
-export interface Principal {
-    userId: string;
-    subject: string;
-    issuer: string;
-    displayName: string;
-    permissions: ArdentStudioPermission[];
-    /** Token expiry in epoch seconds. Streams close at this time. */
-    expiresAt: number;
-}
-/** The token is valid but its subject has no explicit link, so the person has no Studio access. */
-export declare class AccessDenied extends Error {
-    name: string;
-}
-/** How long a userinfo answer is reused, measured from when the request started. */
-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;
-export declare function createOathweaveVerifier(options: OathweaveOptions, overrides?: {
-    keys?: JWTVerifyGetKey;
-    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 declare function createAuthenticator(verify: OathweaveVerifier, links: readonly IdentityLink[]): Authenticator;

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,
-        };
-    };
-}