@sequenceholdings/managed-functions 0.4.0 → 0.4.2

package/dist/abrigo-response.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAbrigoReviewResponse = validateAbrigoReviewResponse;
+const zod_1 = require("zod");
+const abrigo_contract_1 = require("./abrigo-contract");
+const positiveId = zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const reviewWorkflowSchema = zod_1.z.strictObject({ id: positiveId, customerId: positiveId });
+const reviewDocumentsSchema = zod_1.z.object({ items: zod_1.z.array(zod_1.z.unknown()).max(500) }).passthrough();
+const reviewCustomerDocumentsSchema = reviewDocumentsSchema.extend({ workflowId: positiveId, customerId: positiveId });
+function validateAbrigoReviewResponse({ query, body }) {
+    const invalid = () => new abrigo_contract_1.FunctionAbrigoReadError(502, 'malformed_response', 'Atlas returned an invalid workflow document review response');
+    if (query.operation === 'reviewWorkflow') {
+        const parsed = reviewWorkflowSchema.safeParse(body);
+        if (!parsed.success || parsed.data.id !== query.workflowId)
+            throw invalid();
+    }
+    else if (query.operation === 'reviewWorkflowDocuments') {
+        const parsed = reviewDocumentsSchema.safeParse(body);
+        if (!parsed.success || parsed.data.items.length > query.perPage)
+            throw invalid();
+    }
+    else if (query.operation === 'reviewWorkflowCustomerDocuments') {
+        const parsed = reviewCustomerDocumentsSchema.safeParse(body);
+        if (!parsed.success || parsed.data.workflowId !== query.workflowId || parsed.data.items.length > query.perPage)
+            throw invalid();
+    }
+}

package/dist/abrigo.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue } from './cache';
+import { type FunctionAbrigoReadRequest } from './abrigo-contract';
+export * from './abrigo-contract';
+export interface FunctionCallerAbrigoOptions {
+    request: {
+        headers: Pick<Headers, 'get'> | Readonly<Record<string, string | readonly string[] | undefined>>;
+    };
+    baseUrl: string;
+    fetchImpl?: typeof globalThis.fetch;
+}
+export interface FunctionCallerAbrigoClient {
+    read(query: FunctionAbrigoReadRequest): Promise<JsonValue>;
+}
+export declare function createFunctionCallerAbrigoClient({ request, baseUrl, fetchImpl }: FunctionCallerAbrigoOptions): FunctionCallerAbrigoClient;

package/dist/abrigo.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFunctionCallerAbrigoClient = createFunctionCallerAbrigoClient;
+const zod_1 = require("zod");
+const abrigo_response_1 = require("./abrigo-response");
+const abrigo_contract_1 = require("./abrigo-contract");
+__exportStar(require("./abrigo-contract"), exports);
+const claimsSchema = zod_1.z.object({
+    audience: zod_1.z.literal(abrigo_contract_1.FUNCTION_ABRIGO_READ_AUDIENCE), environment: zod_1.z.string().min(1).max(4096),
+    functionId: zod_1.z.uuid(), versionId: zod_1.z.uuid(), invocationId: zod_1.z.uuid(), serviceAccountId: zod_1.z.uuid(),
+    org: zod_1.z.string().min(1).max(255), callerKind: zod_1.z.literal('human'),
+    callerSub: zod_1.z.string().min(1).max(512).regex(/^[^\s:#|]+\|[^\s:#]+$/).refine((sub) => !sub.startsWith('service-account|') && !sub.startsWith('managed-function|') &&
+        !sub.startsWith('system|') && !sub.endsWith('@clients') && sub !== 'google-apps|sequence.agent@seqholdings.com', 'Only actual human callers may read Abrigo'),
+    callerAuthenticationMethod: zod_1.z.string().min(1).max(64),
+    exp: zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+});
+function credential({ request }) {
+    const invalid = () => new abrigo_contract_1.FunctionAbrigoReadError(401, 'invalid_context', 'This invocation has no valid caller Abrigo read credential');
+    const headers = request.headers;
+    const matches = typeof headers.get === 'function' ? [headers.get(abrigo_contract_1.FUNCTION_ABRIGO_READ_TOKEN_HEADER)]
+        : Object.entries(headers).filter(([name]) => name.toLowerCase() === abrigo_contract_1.FUNCTION_ABRIGO_READ_TOKEN_HEADER).map(([, value]) => value);
+    const token = matches[0];
+    if (matches.length !== 1 || typeof token !== 'string' || token.length > 16_384)
+        throw invalid();
+    const envelope = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!envelope?.[1])
+        throw invalid();
+    let value;
+    try {
+        const decoded = Buffer.from(envelope[1], 'base64url');
+        if (decoded.toString('base64url') !== envelope[1])
+            throw invalid();
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(decoded));
+    }
+    catch {
+        throw invalid();
+    }
+    const parsed = claimsSchema.safeParse(value);
+    if (!parsed.success)
+        throw invalid();
+    return { token, expiresAt: parsed.data.exp };
+}
+function origin(baseUrl) {
+    const invalid = () => new abrigo_contract_1.FunctionAbrigoReadError(400, 'invalid_configuration', 'Configure a trusted HTTPS Atlas origin without credentials, path, query or fragment');
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw invalid();
+    }
+    const loopback = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((!loopback && url.protocol !== 'https:') || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+        throw invalid();
+    return url.origin;
+}
+function validJson(value, depth = 0) {
+    if (depth > 64)
+        return false;
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value));
+    if (Array.isArray(value))
+        return value.every((item) => validJson(item, depth + 1));
+    return typeof value === 'object' && Object.values(value).every((item) => validJson(item, depth + 1));
+}
+async function boundedBody(response) {
+    const oversized = () => new abrigo_contract_1.FunctionAbrigoReadError(502, 'response_too_large', 'Abrigo read exceeded the bounded response size; reduce perPage');
+    const length = response.headers.get('content-length');
+    if (length && /^\d+$/.test(length) && Number(length) > abrigo_contract_1.ABRIGO_READ_MAX_RESPONSE_BYTES) {
+        await response.body?.cancel().catch(() => { });
+        throw oversized();
+    }
+    if (!response.body)
+        throw new abrigo_contract_1.FunctionAbrigoReadError(502, 'malformed_response', 'Atlas returned invalid Abrigo JSON');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.byteLength;
+            if (bytes > abrigo_contract_1.ABRIGO_READ_MAX_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => { });
+                throw oversized();
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, bytes)));
+    }
+    catch {
+        throw new abrigo_contract_1.FunctionAbrigoReadError(502, 'malformed_response', 'Atlas returned invalid Abrigo JSON');
+    }
+}
+function createFunctionCallerAbrigoClient({ request, baseUrl, fetchImpl = globalThis.fetch }) {
+    const url = `${origin(baseUrl)}${abrigo_contract_1.FUNCTION_ABRIGO_READ_PATH}`;
+    const { token, expiresAt } = credential({ request });
+    return {
+        async read(input) {
+            if (expiresAt <= Date.now() / 1000)
+                throw new abrigo_contract_1.FunctionAbrigoReadError(401, 'expired_context', 'The Abrigo read credential expired; start a new invocation');
+            const query = abrigo_contract_1.functionAbrigoReadRequestSchema.safeParse(input);
+            if (!query.success)
+                throw new abrigo_contract_1.FunctionAbrigoReadError(400, 'invalid_request', 'Invalid bounded Abrigo read request');
+            try {
+                const response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json', [abrigo_contract_1.FUNCTION_ABRIGO_READ_TOKEN_HEADER]: token }, body: JSON.stringify(query.data), redirect: 'error', signal: AbortSignal.timeout(abrigo_contract_1.ABRIGO_READ_TIMEOUT_MS) });
+                const body = await boundedBody(response).catch((error) => {
+                    if (!response.ok && error instanceof abrigo_contract_1.FunctionAbrigoReadError && error.code === 'malformed_response')
+                        return null;
+                    throw error;
+                });
+                if (!response.ok) {
+                    const error = zod_1.z.object({ code: zod_1.z.string().max(128).regex(/^[a-z][a-z0-9_]*$/).optional() }).safeParse(body);
+                    throw new abrigo_contract_1.FunctionAbrigoReadError(response.status, error.success ? error.data.code ?? 'abrigo_read_failed' : 'abrigo_read_failed', 'The authorized Abrigo read failed');
+                }
+                if (!validJson(body))
+                    throw new abrigo_contract_1.FunctionAbrigoReadError(502, 'malformed_response', 'Atlas returned invalid Abrigo JSON');
+                (0, abrigo_response_1.validateAbrigoReviewResponse)({ query: query.data, body });
+                return body;
+            }
+            catch (error) {
+                if (error instanceof abrigo_contract_1.FunctionAbrigoReadError)
+                    throw error;
+                throw new abrigo_contract_1.FunctionAbrigoReadError(503, 'abrigo_read_unavailable', 'The authorized Abrigo read could not be completed');
+            }
+        },
+    };
+}

package/dist/agent-evidence.d.ts

@@ -0,0 +1,9 @@
+import { type FunctionServiceAgentsOptions } from './agents';
+import { type FunctionAgentSourceEvidenceRequest, type FunctionAgentConversationEvidenceRequest, type FunctionAgentSourceEvidenceVerification } from './agent-source-evidence-contract';
+export type FunctionAgentSourceEvidenceInput = Omit<FunctionAgentSourceEvidenceRequest, 'operation'>;
+export type FunctionAgentConversationEvidenceInput = Omit<FunctionAgentConversationEvidenceRequest, 'operation'>;
+export interface FunctionAgentEvidenceClient {
+    verifySourceEvidence(input: FunctionAgentSourceEvidenceInput): Promise<FunctionAgentSourceEvidenceVerification>;
+    verifyConversationEvidence(input: FunctionAgentConversationEvidenceInput): Promise<FunctionAgentSourceEvidenceVerification>;
+}
+export declare function createFunctionAgentEvidenceClient({ request, baseUrl, fetchImpl }: FunctionServiceAgentsOptions): FunctionAgentEvidenceClient;

package/dist/agent-evidence.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFunctionAgentEvidenceClient = createFunctionAgentEvidenceClient;
+const zod_1 = require("zod");
+const agents_1 = require("./agents");
+const agent_source_evidence_contract_1 = require("./agent-source-evidence-contract");
+function header(request, name) {
+    const { headers } = request;
+    const values = typeof headers.get === 'function' ? [headers.get(name)] : Object.entries(headers).filter(([key]) => key.toLowerCase() === name).map(([, value]) => value);
+    return values.length === 1 && typeof values[0] === 'string' ? values[0] : null;
+}
+const bindingSchema = zod_1.z.object({ audience: zod_1.z.literal('atlas-managed-function-agent-evidence'), sub: zod_1.z.string().startsWith('service-account|'), functionId: zod_1.z.uuid(), versionId: zod_1.z.uuid(), invocationId: zod_1.z.uuid(), serviceAccountId: zod_1.z.uuid(), org: zod_1.z.string().min(1), exp: zod_1.z.number().int() });
+function invocation(request) {
+    const denied = () => new agents_1.FunctionAgentReadError(401, 'invalid_context', 'This invocation has no valid agent-evidence credential');
+    const token = header(request, agent_source_evidence_contract_1.FUNCTION_AGENT_EVIDENCE_TOKEN_HEADER);
+    const body = token && token.length <= 16_384 ? /^([A-Za-z0-9_-]+)\.[A-Za-z0-9_-]{43}$/.exec(token)?.[1] : null;
+    if (!body || !token)
+        throw denied();
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw denied();
+    }
+    const binding = bindingSchema.safeParse(value);
+    if (!binding.success || binding.data.sub !== `service-account|${binding.data.serviceAccountId}`)
+        throw denied();
+    return { token, binding: binding.data };
+}
+function origin(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new agents_1.FunctionAgentReadError(400, 'invalid_configuration', 'Configure a trusted Atlas origin');
+    }
+    const loopback = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((!loopback && url.protocol !== 'https:') || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+        throw new agents_1.FunctionAgentReadError(400, 'invalid_configuration', 'Configure an HTTPS Atlas origin without credentials, path, query or fragment');
+    return url.origin;
+}
+function createFunctionAgentEvidenceClient({ request, baseUrl, fetchImpl = globalThis.fetch }) {
+    const url = `${origin(baseUrl)}${agent_source_evidence_contract_1.FUNCTION_AGENT_EVIDENCE_PATH}`;
+    const { token, binding } = invocation(request);
+    const lattice = header(request, 'x-sequence-lattice-execution-token');
+    async function verify(input) {
+        if (binding.exp <= Date.now() / 1000)
+            throw new agents_1.FunctionAgentReadError(401, 'expired_context', 'The agent-evidence credential expired; start a new invocation');
+        const body = JSON.stringify(input);
+        if (Buffer.byteLength(body, 'utf8') > agent_source_evidence_contract_1.AGENT_SOURCE_VERIFY_MAX_BYTES)
+            throw new agents_1.FunctionAgentReadError(413, 'source_evidence_too_large', 'Source verification exceeds 768 KiB; capture a smaller source before writing');
+        const response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json', [agent_source_evidence_contract_1.FUNCTION_AGENT_EVIDENCE_TOKEN_HEADER]: token, ...(lattice ? { 'x-sequence-lattice-execution-token': lattice } : {}) }, body, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+        const result = await response.json().catch(() => null);
+        if (!response.ok) {
+            const error = zod_1.z.object({ detail: zod_1.z.string().max(2000).optional(), code: zod_1.z.string().max(128).optional() }).safeParse(result);
+            throw new agents_1.FunctionAgentReadError(response.status, error.success ? (error.data.code ?? 'agent_evidence_failed') : 'agent_evidence_failed', error.success ? (error.data.detail ?? 'Source verification failed') : 'Source verification failed');
+        }
+        const verified = agent_source_evidence_contract_1.functionAgentSourceEvidenceVerificationSchema.safeParse(result);
+        if (!verified.success)
+            throw new agents_1.FunctionAgentReadError(502, 'malformed_response', 'Atlas returned invalid source verification');
+        const { source, receiver } = verified.data;
+        const execution = verified.data.lattice;
+        if (source.agentId !== input.agent || source.threadId !== input.response.threadId || source.responseHash !== input.responseHash || receiver.functionId !== binding.functionId || receiver.versionId !== binding.versionId || receiver.invocationId !== binding.invocationId || receiver.serviceAccountId !== binding.serviceAccountId || receiver.org !== binding.org ||
+            (execution !== null && (execution.receiverFunctionOrgId !== receiver.org || execution.receiver.functionId !== receiver.functionId || execution.receiver.versionId !== receiver.versionId || execution.receiver.invocationId !== receiver.invocationId)))
+            throw new agents_1.FunctionAgentReadError(502, 'malformed_response', 'Atlas returned source verification for another request or invocation');
+        return verified.data;
+    }
+    return {
+        async verifySourceEvidence(input) {
+            const result = await verify(agent_source_evidence_contract_1.functionAgentSourceEvidenceRequestSchema.parse({ ...input, operation: 'verifySourceEvidence' }));
+            if (result.source.projection === 'thread-conversation-v1' || result.source.runId !== input.runId)
+                throw new agents_1.FunctionAgentReadError(502, 'malformed_response', 'Atlas returned evidence for a different completed source');
+            return result;
+        },
+        async verifyConversationEvidence(input) {
+            const result = await verify(agent_source_evidence_contract_1.functionAgentConversationEvidenceRequestSchema.parse({ ...input, operation: 'verifyConversationEvidence' }));
+            if (result.source.projection !== 'thread-conversation-v1' || result.source.threadId !== input.threadId || result.source.revision !== input.response.revision || result.source.cutoffAt !== input.response.cutoffAt)
+                throw new agents_1.FunctionAgentReadError(502, 'malformed_response', 'Atlas returned evidence for a different settled conversation');
+            return result;
+        },
+    };
+}