aimeat 2.7.0 → 3.0.0

package/dist/src/services/capability-record.js

@@ -0,0 +1,298 @@
+/**
+ * @file src/services/capability-record.ts
+ * @description Writing a capability, once, for whichever door is doing the writing.
+ *
+ *   WHY THIS FILE EXISTS. `POST/PUT/DELETE /v1/capabilities`, the vouch and invoke routes, and the
+ *   `aimeat_capabilities_*` tools are the same operations, and each door had written them out for
+ *   itself. Step 3 of the August 2026 audit moved the record SHAPE here: thirty fields, written
+ *   twice, agreeing on twenty-nine, with nobody in a position to notice the thirtieth drifting.
+ *   Step 8 moved the rest of the write, because the rest is where the differences were:
+ *
+ *     - The operator was exempt from the node's publishing policy on the HTTP door and nowhere
+ *       else. `capabilityPublishing` defaults to 'disabled', so on an ordinary node the operator's
+ *       own agent was refused a capability the operator could create by hand a minute later.
+ *     - Publishing a PUBLIC capability on a MODERATED node waits for review at create, on both
+ *       doors. At UPDATE only the tool applied it, so `PUT /v1/capabilities/:id { status:'active' }`
+ *       walked straight past the review the tool respected.
+ *     - An operator could act on another owner's capability over HTTP and not over MCP.
+ *     - Every invocation through the HTTP door wrote a call-log entry, with the owner's redaction
+ *       rules applied to the input. The same invocation through the tool surface wrote none, so the
+ *       log a capability owner reads to see who called them had a hole exactly the shape of the
+ *       agent traffic, which is most of it.
+ *
+ *   WHAT IS STILL PER-DOOR, deliberately. The caller's identity: an HTTP session resolves it with
+ *   `resolveIdentity()`, a tool session builds it from the agent's GAII. Both arrive here as
+ *   `CapabilityCaller.gaii` and this file compares whatever it is given, so the day that decision is
+ *   settled it is settled in the doors rather than in the write.
+ * @structure
+ *   - CapabilityCaller / CapabilityResult — who is asking, and the refusal each door renders itself
+ *   - moderatedStatus() / buildCapabilityRecord() — the status rule, and the thirty-field record
+ *   - createCapability() / updateCapability() / deleteCapability() / vouchCapability()
+ *   - recordCapabilityInvocation() — stats and the redacted call log, after an invoke
+ * @usage
+ *   const out = await createCapability({ storage, config }, caller, input);
+ *   if (!out.ok) return renderRefusal(out);   // each door renders its own answer
+ * @version-history
+ *   v1.0.0 — 2026-08-11 — Extracted after the copied-logic check found the pair.
+ *   v1.1.0 — 2026-08-11 — The whole write moves here (August 2026 audit step 8): create, update,
+ *     delete, vouch and the post-invoke record, with the four differences above collapsed onto the
+ *     HTTP door's behaviour, apart from the update-time moderation gate where the tool was right.
+ */
+import { randomUUID, createHash } from 'node:crypto';
+import { logger } from '../utils/logger.js';
+function refuse(status, code, message) {
+    return { ok: false, status, code, message };
+}
+const CAPABILITY_SOURCE_TYPES = ['extension', 'action', 'cortex', 'app', 'manual', 'ecosystem'];
+/**
+ * A PUBLIC capability on a moderated node waits for review, whoever registered it and whichever door
+ * they came through. An operator is exempt — moderating your own node is not a queue you join.
+ */
+export function moderatedStatus(config, visibility, isOperator, requested) {
+    if (!isOperator && config.capabilityPublishing === 'moderated' && visibility === 'public')
+        return 'pending_review';
+    return requested;
+}
+/**
+ * Build the record. `status` is already decided by the caller, because the moderation rule needs to
+ * know whether the caller is an operator and that is a per-door fact.
+ */
+export function buildCapabilityRecord(ctx, input) {
+    return {
+        id: input.id || randomUUID(),
+        name: input.name || '',
+        summary: input.summary || '',
+        ownerGhii: ctx.ownerGhii,
+        visibility: input.visibility || 'private',
+        scope: 'local',
+        status: ctx.status,
+        rejectionReason: null,
+        deprecationMessage: null,
+        replacedBy: null,
+        source: input.source ?? { type: 'manual', ref: 'manual', version: '1.0.0' },
+        authRequired: input.authRequired || 'registered',
+        callable: input.callable ?? false,
+        inputSchema: (input.inputSchema ?? null),
+        outputSchema: (input.outputSchema ?? null),
+        exports: (input.exports ?? null),
+        usage: input.usage || '',
+        whenToUse: input.whenToUse || '',
+        whenNotToUse: input.whenNotToUse || '',
+        examples: (input.examples || []),
+        dependencies: (input.dependencies || []),
+        schemaHash: ctx.schemaHash,
+        webhookUrl: input.webhookUrl ?? null,
+        cost: (input.cost ?? null),
+        trustRequired: (input.trustRequired ?? null),
+        trust: { operatorReviewed: false, reviewedAt: null, vouchCount: 0, publisherTrustScore: 0, codeAudited: false, auditNotes: null },
+        redactedFields: input.redactedFields || [],
+        operatorOverride: null,
+        stats: { totalInvocations: 0, successCount: 0, errorCount: 0, lastInvokedAt: null, avgResponseMs: 0, lastError: null },
+        tags: input.tags || [],
+        createdAt: ctx.now,
+        updatedAt: ctx.now,
+    };
+}
+/**
+ * `source` is required in full by CapabilityRecord (type + ref + version), and sourceRef is NOT NULL
+ * on both backends. Defaulting only when source was ABSENT let a partial object — the natural
+ * `{type:'manual'}` — reach the insert with ref undefined and crash it into a 500. Normalise per
+ * field, and refuse the cases where a placeholder ref would produce an unresolvable record.
+ */
+function normaliseSource(raw) {
+    const obj = (raw && typeof raw === 'object') ? raw : {};
+    const type = (obj.type ?? 'manual');
+    if (!CAPABILITY_SOURCE_TYPES.includes(type)) {
+        return refuse(400, 'INVALID_INPUT', `source.type must be one of: ${CAPABILITY_SOURCE_TYPES.join(', ')}`);
+    }
+    const ref = typeof obj.ref === 'string' && obj.ref ? obj.ref : (type === 'manual' ? 'manual' : '');
+    if (!ref)
+        return refuse(400, 'INVALID_INPUT', `source.ref is required for source.type '${type}'`);
+    const version = typeof obj.version === 'string' && obj.version ? obj.version : '1.0.0';
+    return { ok: true, value: { type, ref, version } };
+}
+/** Register one capability. Policy first, then the shape, then the insert. */
+export async function createCapability(deps, caller, input) {
+    const { storage, config } = deps;
+    // Who may offer work to others is the operator's decision, not a per-surface accident. The
+    // operator is exempt: this was the HTTP door's rule and nowhere else, which on a default node
+    // ('disabled') meant the operator's own agent could not create what the operator could.
+    if (!caller.isOperator) {
+        if (config.capabilityPublishing === 'disabled') {
+            return refuse(403, 'PUBLISHING_DISABLED', 'Only the operator can create capabilities on this node');
+        }
+        if (config.capabilityPublishing === 'self_only' && input.visibility === 'public') {
+            return refuse(403, 'PUBLIC_DISABLED', 'Public capabilities require operator approval. Use visibility: private');
+        }
+    }
+    // Webhook domain allowlist, checked against the source the caller SENT. Omitting `source`
+    // entirely therefore skips it, even though the record is then built as a manual capability
+    // carrying the webhook. That gap is the HTTP door's and predates this file; it is reported in
+    // the August 2026 audit rather than closed here, because closing it moves a gate.
+    const rawSource = (input.source && typeof input.source === 'object') ? input.source : {};
+    if (input.webhookUrl && rawSource.type === 'manual') {
+        if (config.capabilityWebhooks === 'disabled') {
+            return refuse(403, 'WEBHOOKS_DISABLED', 'Webhook capabilities are disabled on this node');
+        }
+        if (config.capabilityWebhooks === 'allowlist_only') {
+            let domain;
+            try {
+                domain = new URL(input.webhookUrl).hostname;
+            }
+            catch {
+                return refuse(400, 'INVALID_WEBHOOK_URL', 'Invalid webhook URL');
+            }
+            if (!config.capabilityWebhookDomainAllowlist.includes(domain)) {
+                return refuse(403, 'WEBHOOK_DOMAIN_NOT_ALLOWED', `Domain '${domain}' is not on the webhook allowlist`);
+            }
+        }
+    }
+    const source = normaliseSource(input.source);
+    if (!source.ok)
+        return source;
+    const schemaHash = createHash('sha256')
+        .update(JSON.stringify(input.inputSchema ?? {}) + JSON.stringify(input.outputSchema ?? {}))
+        .digest('hex').slice(0, 16);
+    const now = new Date().toISOString();
+    const record = buildCapabilityRecord({
+        ownerGhii: caller.gaii,
+        schemaHash,
+        now,
+        // Default 'draft': nothing reaches the catalogue that the owner did not mean to put
+        // there. The moderation rule can still override an 'active' request.
+        status: moderatedStatus(config, input.visibility, caller.isOperator, input.status || 'draft'),
+    }, { ...input, source: source.value });
+    try {
+        return { ok: true, value: await storage.createCapability(record) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('UNIQUE') || message.includes('duplicate')) {
+            return refuse(409, 'CAPABILITY_EXISTS', `Capability '${record.id}' already exists`);
+        }
+        throw err;
+    }
+}
+/**
+ * Apply one patch. WHICH fields a door accepts is the door's own declaration — an MCP tool publishes
+ * a parameter list, an HTTP route takes a body — so the patch arrives already shaped. What happens
+ * to it is the same either way.
+ */
+export async function updateCapability(deps, caller, id, patch) {
+    const { storage, config } = deps;
+    const cap = await storage.getCapability(id);
+    if (!cap)
+        return refuse(404, 'NOT_FOUND', 'Capability not found');
+    if (cap.ownerGhii !== caller.gaii && !caller.isOperator) {
+        return refuse(403, 'FORBIDDEN', 'Not the owner');
+    }
+    const updates = { ...patch, updatedAt: new Date().toISOString() };
+    // Identity and birth date belong to the record, never to the patch.
+    delete updates.id;
+    delete updates.ownerGhii;
+    delete updates.createdAt;
+    // Going ACTIVE with a public capability on a moderated node is the same decision as at create,
+    // and it was enforced on the tool door only: the HTTP door published past the review. Only a
+    // request to go active is redirected, so unpublishing or retiring never waits for anyone.
+    if (updates.status === 'active') {
+        updates.status = moderatedStatus(config, updates.visibility ?? cap.visibility, caller.isOperator, 'active');
+    }
+    const updated = await storage.updateCapability(id, updates);
+    if (!updated)
+        return refuse(404, 'NOT_FOUND', 'Capability not found');
+    return { ok: true, value: updated };
+}
+/** Remove one capability. Only a manual one: the rest belong to whatever produced them. */
+export async function deleteCapability(deps, caller, id) {
+    const { storage } = deps;
+    const cap = await storage.getCapability(id);
+    if (!cap)
+        return refuse(404, 'NOT_FOUND', 'Capability not found');
+    if (cap.ownerGhii !== caller.gaii && !caller.isOperator) {
+        return refuse(403, 'FORBIDDEN', 'Not the owner');
+    }
+    if (cap.source.type !== 'manual') {
+        return refuse(400, 'CANNOT_DELETE', 'Only manual capabilities can be deleted. Auto-aggregated capabilities are removed when their source is removed.');
+    }
+    await storage.deleteCapability(id);
+    return { ok: true, value: { id } };
+}
+/** Vouch for someone else's capability. Your own does not count, which is the whole point. */
+export async function vouchCapability(deps, caller, id) {
+    const { storage } = deps;
+    const cap = await storage.getCapability(id);
+    if (!cap)
+        return refuse(404, 'NOT_FOUND', 'Capability not found');
+    if (cap.ownerGhii === caller.gaii) {
+        return refuse(400, 'CANNOT_VOUCH_OWN', 'Cannot vouch for your own capability');
+    }
+    await storage.incrementVouchCount(id);
+    const updated = await storage.getCapability(id);
+    return { ok: true, value: { vouchCount: updated?.trust.vouchCount ?? 0 } };
+}
+/**
+ * Hide the fields the capability owner marked. `*` replaces the whole input with a hash, which still
+ * proves two calls carried the same arguments without keeping either.
+ */
+function redactInput(input, redactedFields) {
+    if (!redactedFields.length)
+        return input;
+    if (redactedFields.includes('*'))
+        return { _redacted: true, _hash: createHash('sha256').update(JSON.stringify(input)).digest('hex').slice(0, 16) };
+    const copy = JSON.parse(JSON.stringify(input));
+    for (const field of redactedFields) {
+        const parts = field.split('.');
+        let obj = copy;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (obj && typeof obj === 'object' && parts[i] in obj)
+                obj = obj[parts[i]];
+            else {
+                obj = null;
+                break;
+            }
+        }
+        if (obj && typeof obj === 'object') {
+            const last = parts[parts.length - 1];
+            if (last in obj)
+                obj[last] = '[REDACTED]';
+        }
+    }
+    return copy;
+}
+/**
+ * What an invocation leaves behind: the counters, and one line in the capability's call log. The
+ * tool surface wrote the counters and no log at all, so the log the owner reads to see who has been
+ * calling them was missing the agent traffic.
+ *
+ * A failed input is logged in full, because a redacted argument list cannot be debugged and the
+ * owner is the only reader. A successful one is logged through the owner's redaction rules.
+ *
+ * Never throws: the call already happened and its answer is owed to the caller either way.
+ */
+export async function recordCapabilityInvocation(deps, cap, callerGhii, input, outcome) {
+    const { storage } = deps;
+    try {
+        await storage.incrementCapabilityStats(cap.id, outcome.ok
+            ? { success: 1, error: 0, totalMs: outcome.durationMs }
+            : { success: 0, error: 1, totalMs: 0, lastError: outcome.message });
+    }
+    catch (err) {
+        logger.warn('capability stats not recorded', { capabilityId: cap.id, error: String(err) });
+    }
+    try {
+        await storage.addCapabilityLog({
+            id: randomUUID(),
+            capabilityId: cap.id,
+            callerGhii,
+            input: outcome.ok ? redactInput(input, cap.redactedFields) : input,
+            status: outcome.ok ? 'success' : 'error',
+            durationMs: outcome.ok ? outcome.durationMs : 0,
+            error: outcome.ok ? null : outcome.message,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        logger.warn('capability call log not written', { capabilityId: cap.id, error: String(err) });
+    }
+}
+//# sourceMappingURL=capability-record.js.map

package/dist/src/services/capability-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-record.js","sourceRoot":"","sources":["../../../src/services/capability-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAqD5C,SAAS,MAAM,CAAC,MAAc,EAAE,IAAY,EAAE,OAAe;IACzD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,uBAAuB,GAAyC,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAEtI;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC3B,MAAoB,EACpB,UAA8B,EAC9B,UAAmB,EACnB,SAAqC;IAErC,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,oBAAoB,KAAK,WAAW,IAAI,UAAU,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC;IACnH,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACjC,GAA+F,EAC/F,KAAsB;IAEtB,OAAO;QACH,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,UAAU,EAAE;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;QAC5B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,SAAS;QACzC,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,eAAe,EAAE,IAAI;QACrB,kBAAkB,EAAE,IAAI;QACxB,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE;QAC3E,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,YAAY;QAChD,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,KAAK;QACjC,WAAW,EAAE,CAAC,KAAK,CAAC,WAAW,IAAI,IAAI,CAAoC;QAC3E,YAAY,EAAE,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAqC;QAC9E,OAAO,EAAE,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAgC;QAC/D,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,EAAE;QAChC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,EAAE;QACtC,QAAQ,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAiC;QAChE,YAAY,EAAE,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAqC;QAC5E,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAA6B;QACtD,aAAa,EAAE,CAAC,KAAK,CAAC,aAAa,IAAI,IAAI,CAAsC;QACjF,KAAK,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE;QACjI,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,EAAE;QAC1C,gBAAgB,EAAE,IAAI;QACtB,KAAK,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;QACtH,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,SAAS,EAAE,GAAG,CAAC,GAAG;QAClB,SAAS,EAAE,GAAG,CAAC,GAAG;KACrB,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,GAAY;IACjC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,GAA8B,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAuC,CAAC;IAC1E,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,OAAO,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,+BAA+B,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7G,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnG,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,2CAA2C,IAAI,GAAG,CAAC,CAAC;IAClG,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACvF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;AACvD,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,IAAoB,EACpB,MAAwB,EACxB,KAA4B;IAE5B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEjC,2FAA2F;IAC3F,8FAA8F;IAC9F,wFAAwF;IACxF,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACrB,IAAI,MAAM,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;YAC7C,OAAO,MAAM,CAAC,GAAG,EAAE,qBAAqB,EAAE,wDAAwD,CAAC,CAAC;QACxG,CAAC;QACD,IAAI,MAAM,CAAC,oBAAoB,KAAK,WAAW,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC/E,OAAO,MAAM,CAAC,GAAG,EAAE,iBAAiB,EAAE,wEAAwE,CAAC,CAAC;QACpH,CAAC;IACL,CAAC;IAED,0FAA0F;IAC1F,2FAA2F;IAC3F,8FAA8F;IAC9F,kFAAkF;IAClF,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpH,IAAI,KAAK,CAAC,UAAU,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAClD,IAAI,MAAM,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;YAC3C,OAAO,MAAM,CAAC,GAAG,EAAE,mBAAmB,EAAE,gDAAgD,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,MAAM,CAAC,kBAAkB,KAAK,gBAAgB,EAAE,CAAC;YACjD,IAAI,MAAc,CAAC;YACnB,IAAI,CAAC;gBACD,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC;YAChD,CAAC;YAAC,MAAM,CAAC;gBACL,OAAO,MAAM,CAAC,GAAG,EAAE,qBAAqB,EAAE,qBAAqB,CAAC,CAAC;YACrE,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,gCAAgC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5D,OAAO,MAAM,CAAC,GAAG,EAAE,4BAA4B,EAAE,WAAW,MAAM,mCAAmC,CAAC,CAAC;YAC3G,CAAC;QACL,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAE9B,MAAM,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC;SAClC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;SAC1F,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEhC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,qBAAqB,CAChC;QACI,SAAS,EAAE,MAAM,CAAC,IAAI;QACtB,UAAU;QACV,GAAG;QACH,oFAAoF;QACpF,qEAAqE;QACrE,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,IAAI,OAAO,CAAC;KAChG,EACD,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CACrC,CAAC;IAEF,IAAI,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9D,OAAO,MAAM,CAAC,GAAG,EAAE,mBAAmB,EAAE,eAAe,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC;QACxF,CAAC;QACD,MAAM,GAAG,CAAC;IACd,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,IAAoB,EACpB,MAAwB,EACxB,EAAU,EACV,KAA8B;IAE9B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACtD,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,OAAO,GAA4B,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IAC3F,oEAAoE;IACpE,OAAO,OAAO,CAAC,EAAE,CAAC;IAClB,OAAO,OAAO,CAAC,SAAS,CAAC;IACzB,OAAO,OAAO,CAAC,SAAS,CAAC;IAEzB,+FAA+F;IAC/F,6FAA6F;IAC7F,0FAA0F;IAC1F,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,GAAG,eAAe,CAC5B,MAAM,EACL,OAAO,CAAC,UAAiC,IAAI,GAAG,CAAC,UAAU,EAC5D,MAAM,CAAC,UAAU,EACjB,QAAQ,CACX,CAAC;IACN,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE,OAAoC,CAAC,CAAC;IACzF,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IACtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,IAAoB,EACpB,MAAwB,EACxB,EAAU;IAEV,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACtD,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,iHAAiH,CAAC,CAAC;IAC3J,CAAC;IAED,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACnC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;AACvC,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,IAAoB,EACpB,MAAwB,EACxB,EAAU;IAEV,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC,GAAG,EAAE,kBAAkB,EAAE,sCAAsC,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,EAAE,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,KAA8B,EAAE,cAAwB;IACzE,IAAI,CAAC,cAAc,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IACnJ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAA4B,CAAC;IAC1E,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,GAAG,GAAmC,IAAI,CAAC;QAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG;gBAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAmC,CAAC;iBACxG,CAAC;gBAAC,GAAG,GAAG,IAAI,CAAC;gBAAC,MAAM;YAAC,CAAC;QAC/B,CAAC;QACD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,IAAI,IAAI,IAAI,GAAG;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;QAC9C,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC5C,IAA0B,EAC1B,GAAqB,EACrB,UAAkB,EAClB,KAA8B,EAC9B,OAA0E;IAE1E,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzB,IAAI,CAAC;QACD,MAAM,OAAO,CAAC,wBAAwB,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE;YACrD,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE;YACvD,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,CAAC;QACD,MAAM,OAAO,CAAC,gBAAgB,CAAC;YAC3B,EAAE,EAAE,UAAU,EAAE;YAChB,YAAY,EAAE,GAAG,CAAC,EAAE;YACpB,UAAU;YACV,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK;YAClE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;YACxC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC/C,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO;YAC1C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC,CAAC;IACP,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;AACL,CAAC"}

package/dist/src/services/chat-instance-write.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @file src/services/chat-instance-write.ts
+ * @description Registering a chat session and marking it alive, once, for every surface that can do it.
+ *
+ *   WHY THIS FILE EXISTS. A chat instance is the row that answers "which chats has this person got
+ *   open, and when was each one last used". Three places built that row, and they had drifted:
+ *
+ *     - `POST /v1/chat-instances` verified the owner's GHII exists before writing; neither MCP path
+ *       did, so an agent could leave a session row pointing at a profile that is not there.
+ *     - `POST /v1/chat-instances` had no upsert: registering the same platform and app name twice
+ *       hit the primary key and surfaced as a 500, while `aimeat_instance_create` returned the
+ *       existing row. The id is deterministic, so re-registering is the normal case for a returning
+ *       session, and the two doors answered it differently.
+ *     - `aimeat_instance_create` stamped `isAnonymous: false` on every row instead of deriving it
+ *       from the owner, and returned an existing row without marking it seen.
+ *     - The MCP session upsert in src/mcp/index.ts created rows without emitting the `chat` change
+ *       event, so a new session appeared in the browser's chat list only after some other event
+ *       happened to refresh it.
+ *
+ *   One capability, one implementation, whatever the interface — CLAUDE.md, Backend.
+ * @structure
+ *   - ChatInstanceCaller / ChatInstanceInput / ChatInstanceResult — the shared shapes
+ *   - registerChatInstance() — validate, verify the GHII, upsert the row, emit the change event
+ *   - touchChatInstance() — move lastSeen forward for a session that is still working
+ * @usage
+ *   const out = await registerChatInstance({ storage, config }, { ownerName }, { platform, appName });
+ *   if (!out.ok) return renderRefusal(out);   // each door renders its own way
+ * @version-history
+ *   v1.0.0 — 2026-08-10 — Initial (August 2026 audit step 8): the write behind POST /v1/chat-instances,
+ *     aimeat_instance_create and the MCP session upsert.
+ */
+import type { AimeatConfig } from '../config.js';
+import type { Storage, ChatInstanceRecord } from '../storage/interface.js';
+export interface ChatInstanceCaller {
+    /**
+     * Bare owner name the session belongs to: `req.auth!.owner` on the HTTP side, the owner segment
+     * of the agent GAII on the MCP side. Never client-supplied — a chat instance is addressed by an
+     * id built from this name, so accepting one from the body would let a caller write another
+     * person's list.
+     */
+    ownerName: string;
+    /** The agent that opened the session, when an agent did. Left unset for a browser session. */
+    agentGaii?: string;
+}
+export interface ChatInstanceInput {
+    platform: string;
+    /** Defaults to `session-<epoch ms>`, which is what an unnamed HTTP registration gets. */
+    appName?: string;
+    /**
+     * An explicit id, for the one caller that cannot use the derived one: MCP session rows have
+     * carried the id `mcp-<platform>#<owner>@<node>` since before buildChatInstanceId existed, and
+     * every session row in production is addressed by it. Deriving it instead would orphan them all.
+     */
+    id?: string;
+}
+export type ChatInstanceResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Register a chat session, or hand back the one that is already there.
+ *
+ * The id is deterministic (platform, app name, owner, node), so a returning session asks for the
+ * same row it had. Existing rows are marked seen rather than refused: a second registration means
+ * the session is alive again, which is exactly what lastSeen records.
+ */
+export declare function registerChatInstance(deps: {
+    storage: Storage;
+    config: AimeatConfig;
+}, caller: ChatInstanceCaller, input: ChatInstanceInput): Promise<ChatInstanceResult<{
+    record: ChatInstanceRecord;
+    created: boolean;
+}>>;
+/**
+ * Move lastSeen forward for a session that is still working.
+ *
+ * `notify` is off for the MCP per-request heartbeat: that fires on every tool call, and a `chat`
+ * event on each one would have every connected browser re-fetching the list dozens of times a
+ * minute. An explicit heartbeat from a client is a single deliberate call, so it notifies.
+ */
+export declare function touchChatInstance(deps: {
+    storage: Storage;
+}, id: string, opts?: {
+    notify?: boolean;
+}): Promise<ChatInstanceRecord | null>;
+//# sourceMappingURL=chat-instance-write.d.ts.map

package/dist/src/services/chat-instance-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-instance-write.d.ts","sourceRoot":"","sources":["../../../src/services/chat-instance-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAI3E,MAAM,WAAW,kBAAkB;IAC/B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACtC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EAChD,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CA0C/E;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACnC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EAC1B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAIpC"}

package/dist/src/services/chat-instance-write.js

@@ -0,0 +1,59 @@
+import { buildChatInstanceId } from '../utils/gaii.js';
+import { emitChange } from './event-bus.js';
+/**
+ * Register a chat session, or hand back the one that is already there.
+ *
+ * The id is deterministic (platform, app name, owner, node), so a returning session asks for the
+ * same row it had. Existing rows are marked seen rather than refused: a second registration means
+ * the session is alive again, which is exactly what lastSeen records.
+ */
+export async function registerChatInstance(deps, caller, input) {
+    const { storage, config } = deps;
+    if (!input.platform || typeof input.platform !== 'string') {
+        return { ok: false, status: 400, code: 'INVALID_INPUT', message: 'platform is required' };
+    }
+    const appName = input.appName || `session-${Date.now()}`;
+    const id = input.id ?? buildChatInstanceId(input.platform, appName, caller.ownerName, config.nodeId);
+    const existing = await storage.getChatInstance(id);
+    if (existing) {
+        const touched = await touchChatInstance({ storage }, id);
+        return { ok: true, value: { record: touched ?? existing, created: false } };
+    }
+    // A session row points at a profile. Without this the row still lists and still answers, and the
+    // GHII it names does not exist.
+    const ghii = `${caller.ownerName}@${config.nodeId}`;
+    const ghiiRecord = await storage.getGHII(ghii);
+    if (!ghiiRecord) {
+        return { ok: false, status: 404, code: 'GHII_NOT_FOUND', message: `No GHII profile found for "${caller.ownerName}"` };
+    }
+    const now = new Date().toISOString();
+    const record = await storage.createChatInstance({
+        id,
+        platform: input.platform,
+        appName,
+        ownerName: caller.ownerName,
+        ghii,
+        nodeId: config.nodeId,
+        isAnonymous: caller.ownerName === 'anonymous',
+        ...(caller.agentGaii ? { agentGaii: caller.agentGaii } : {}),
+        createdAt: now,
+        lastSeen: now,
+    });
+    // The chat list in the browser listens on this.
+    emitChange('chat');
+    return { ok: true, value: { record, created: true } };
+}
+/**
+ * Move lastSeen forward for a session that is still working.
+ *
+ * `notify` is off for the MCP per-request heartbeat: that fires on every tool call, and a `chat`
+ * event on each one would have every connected browser re-fetching the list dozens of times a
+ * minute. An explicit heartbeat from a client is a single deliberate call, so it notifies.
+ */
+export async function touchChatInstance(deps, id, opts = {}) {
+    const updated = await deps.storage.updateChatInstance(id, { lastSeen: new Date().toISOString() });
+    if (opts.notify !== false)
+        emitChange('chat');
+    return updated;
+}
+//# sourceMappingURL=chat-instance-write.js.map

package/dist/src/services/chat-instance-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-instance-write.js","sourceRoot":"","sources":["../../../src/services/chat-instance-write.ts"],"names":[],"mappings":"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"}

package/dist/src/services/company/company-portfolio.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file src/services/company/company-portfolio.ts
+ * @description A company's own HTML page: publish it, read what is published, remove it.
+ *   This is the company-scale twin of the personal portfolio — same idea (a standalone
+ *   document the owner wrote, served on an isolated origin), different address family:
+ *   a personal portfolio answers on {user}.portfolio.<apex>, a company's on {slug}.co.<apex>.
+ *
+ *   Stored as a PUBLIC storage file under the OWNER's GHII, keyed by company id
+ *   (`company/{id}/index.html`). Keying on the id rather than the slug means the page
+ *   survives anything that ever renames an address, and keeping it under the owner means
+ *   the owner's storage quota is the one that applies — a company is not a separate tenant.
+ *
+ *   Publishing IS the act of choosing the front page: a founder who uploads a page means
+ *   for it to be served, and making them then find a dropdown would be a second step that
+ *   exists only because the data model has two fields.
+ *
+ * @structure companyPortfolioKey · publishCompanyPortfolio · getCompanyPortfolio ·
+ *   readCompanyPortfolioHtml · deleteCompanyPortfolio
+ * @usage await publishCompanyPortfolio(config, storage, ownerGhii, companyId, html);
+ * @version-history
+ *   v1.0.0 — 2026-08-08 — A company's own front page as raw HTML.
+ */
+import type { AimeatConfig } from '../../config.js';
+import type { Storage } from '../../storage/interface.js';
+import type { CompanyRecord } from '../../models/company-schemas.js';
+/** Where a company's page lives in the owner's storage namespace. */
+export declare function companyPortfolioKey(companyId: string): string;
+export interface CompanyPortfolioStatus {
+    published: boolean;
+    sizeBytes: number;
+    updatedAt: string | null;
+}
+/**
+ * Replaces the company's page and points the address at it. Returns the updated company so
+ * the caller can report the front page without a second read.
+ */
+export declare function publishCompanyPortfolio(config: AimeatConfig, storage: Storage, ownerGhii: string, companyId: string, html: string): Promise<{
+    company: CompanyRecord;
+    status: CompanyPortfolioStatus;
+}>;
+/** What is published, without moving the bytes — the shape the settings UI reads. */
+export declare function getCompanyPortfolio(storage: Storage, ownerGhii: string, companyId: string): Promise<CompanyPortfolioStatus>;
+/**
+ * The bytes, for the serving path. Takes the company record (the co origin already resolved
+ * it from the slug) so serving never needs a second ownership check.
+ */
+export declare function readCompanyPortfolioHtml(storage: Storage, company: CompanyRecord): Promise<string | null>;
+/**
+ * Removes the page. The address falls back to serving nothing rather than silently keeping a
+ * front-page setting that points at a document which no longer exists.
+ */
+export declare function deleteCompanyPortfolio(storage: Storage, ownerGhii: string, companyId: string): Promise<CompanyRecord>;
+//# sourceMappingURL=company-portfolio.d.ts.map

package/dist/src/services/company/company-portfolio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-portfolio.d.ts","sourceRoot":"","sources":["../../../../src/services/company/company-portfolio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGrE,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAOD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GACzF,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAmCrE;AAED,qFAAqF;AACrF,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GACrD,OAAO,CAAC,sBAAsB,CAAC,CAKjC;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG/G;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GACrD,OAAO,CAAC,aAAa,CAAC,CASxB"}

package/dist/src/services/company/company-portfolio.js

@@ -0,0 +1,78 @@
+import { CompanyError, requireOwnCompany } from './company-service.js';
+/** Where a company's page lives in the owner's storage namespace. */
+export function companyPortfolioKey(companyId) {
+    return `company/${companyId}/index.html`;
+}
+/** The size ceiling, shared with the personal portfolio so one page cannot outgrow the other. */
+function maxBytes(config) {
+    return (config.portfolioMaxSizeKb ?? 512) * 1024;
+}
+/**
+ * Replaces the company's page and points the address at it. Returns the updated company so
+ * the caller can report the front page without a second read.
+ */
+export async function publishCompanyPortfolio(config, storage, ownerGhii, companyId, html) {
+    const company = await requireOwnCompany(storage, ownerGhii, companyId);
+    const trimmed = (html ?? '').trim();
+    if (!trimmed)
+        throw new CompanyError('INVALID_PORTFOLIO', 400, 'The page is empty');
+    const data = Buffer.from(trimmed, 'utf-8');
+    if (data.length > maxBytes(config)) {
+        throw new CompanyError('QUOTA_EXCEEDED', 413, `The page exceeds the ${config.portfolioMaxSizeKb ?? 512}KB limit`);
+    }
+    // Anything that is not a document would be served as text/html anyway, so refusing here is
+    // the difference between a clear error now and a blank white address later.
+    if (!/<[a-z!][\s\S]*>/i.test(trimmed)) {
+        throw new CompanyError('INVALID_PORTFOLIO', 400, 'The page does not look like HTML');
+    }
+    const key = companyPortfolioKey(company.id);
+    await storage.deleteStorageFile(ownerGhii, key);
+    const now = new Date().toISOString();
+    await storage.createStorageFile({
+        key,
+        ownerGaii: ownerGhii,
+        visibility: 'public',
+        mimeType: 'text/html',
+        size: data.length,
+        data,
+        createdAt: now,
+    });
+    let updated = company;
+    if (company.frontPage.kind !== 'portfolio') {
+        updated = { ...company, frontPage: { kind: 'portfolio', target: '' }, updatedAt: now };
+        await storage.updateCompany(updated);
+    }
+    return { company: updated, status: { published: true, sizeBytes: data.length, updatedAt: now } };
+}
+/** What is published, without moving the bytes — the shape the settings UI reads. */
+export async function getCompanyPortfolio(storage, ownerGhii, companyId) {
+    const company = await requireOwnCompany(storage, ownerGhii, companyId);
+    const file = await storage.getStorageFile(ownerGhii, companyPortfolioKey(company.id));
+    if (!file)
+        return { published: false, sizeBytes: 0, updatedAt: null };
+    return { published: true, sizeBytes: file.size, updatedAt: file.createdAt };
+}
+/**
+ * The bytes, for the serving path. Takes the company record (the co origin already resolved
+ * it from the slug) so serving never needs a second ownership check.
+ */
+export async function readCompanyPortfolioHtml(storage, company) {
+    const file = await storage.getStorageFile(company.ownerGhii, companyPortfolioKey(company.id));
+    return file ? file.data.toString('utf-8') : null;
+}
+/**
+ * Removes the page. The address falls back to serving nothing rather than silently keeping a
+ * front-page setting that points at a document which no longer exists.
+ */
+export async function deleteCompanyPortfolio(storage, ownerGhii, companyId) {
+    const company = await requireOwnCompany(storage, ownerGhii, companyId);
+    await storage.deleteStorageFile(ownerGhii, companyPortfolioKey(company.id));
+    if (company.frontPage.kind !== 'portfolio')
+        return company;
+    const next = {
+        ...company, frontPage: { kind: 'none', target: '' }, updatedAt: new Date().toISOString(),
+    };
+    await storage.updateCompany(next);
+    return next;
+}
+//# sourceMappingURL=company-portfolio.js.map

package/dist/src/services/company/company-portfolio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-portfolio.js","sourceRoot":"","sources":["../../../../src/services/company/company-portfolio.ts"],"names":[],"mappings":"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"}