@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/bin/verify-publication.mjs

@@ -0,0 +1,317 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+const maxBytes = 4 * 1024 * 1024;
+
+// The operator chooses one origin. Redirects are evidence and are never followed with credentials.
+async function readResponse(url, origin) {
+  const target = new URL(url);
+  if (
+    target.origin !== origin ||
+    target.username ||
+    target.password ||
+    !['http:', 'https:'].includes(target.protocol)
+  )
+    throw Error('invalid-target');
+  const response = await fetch(target, {
+    redirect: 'manual',
+    credentials: 'omit',
+    signal: AbortSignal.timeout(10000),
+  });
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body ?? []) {
+    size += chunk.byteLength;
+    if (size > maxBytes) throw Error('response-too-large');
+    chunks.push(chunk);
+  }
+  return {
+    status: response.status,
+    type: (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase(),
+    bytes: Buffer.concat(chunks),
+  };
+}
+
+// The CLI can attest only to protocols for which it has an independent read-only probe.
+export async function verifyProtocol(declaration) {
+  if (declaration.protocol !== 'openapi') return false;
+  const reply = await readResponse(declaration.url, new URL(declaration.url).origin);
+  if (reply.status !== 200 || !/^(application\/(?:json|[\w.+-]+\+json))$/.test(reply.type))
+    return false;
+  const doc = JSON.parse(reply.bytes.toString('utf8'));
+  const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+  const methods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+  return (
+    /^3\.\d+\.\d+$/.test(doc?.openapi) &&
+    typeof doc.info?.title === 'string' &&
+    doc.info.title.trim().length > 0 &&
+    typeof doc.info?.version === 'string' &&
+    doc.info.version.trim().length > 0 &&
+    record(doc.paths) &&
+    Object.entries(doc.paths).some(
+      ([path, item]) =>
+        path.startsWith('/') &&
+        record(item) &&
+        Object.entries(item).some(
+          ([method, operation]) =>
+            methods.has(method) &&
+            record(operation) &&
+            record(operation.responses) &&
+            Object.entries(operation.responses).some(
+              ([code, response]) =>
+                /^(?:default|[1-5](?:\d\d|XX))$/.test(code) &&
+                record(response) &&
+                typeof response.description === 'string' &&
+                response.description.trim().length > 0,
+            ),
+        ),
+    )
+  );
+}
+
+function attr(tag, name) {
+  const attributes = tag.replace(/^<[\w:-]+/, '');
+  for (const [, key, quoted, single, bare] of attributes.matchAll(
+    /\s+([^\s=/><]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s><]+)))?/g,
+  )) {
+    if (key.toLowerCase() === name) return quoted ?? single ?? bare ?? '';
+  }
+  return '';
+}
+
+function textContent(html) {
+  const entities = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+  return html
+    .replace(/<(script|style|template|noscript|textarea|title)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(
+      /<\/?(?:p|br|div|main|h[1-6]|li|section|article|tr|td|nav|header|footer)\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi,
+      ' ',
+    )
+    .replace(/<\/?[a-z][\w:-]*\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi, '')
+    .replace(/&(#x[\da-f]+|#\d+|amp|lt|gt|quot|apos|nbsp);/gi, (original, entity) => {
+      if (!entity.startsWith('#')) return entities[entity.toLowerCase()] ?? original;
+      const n =
+        entity[1].toLowerCase() === 'x'
+          ? Number.parseInt(entity.slice(2), 16)
+          : Number(entity.slice(1));
+      return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : original;
+    })
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function containsFact(visible, fact) {
+  // Require a word boundary where the approved text starts or ends in a word.
+  // Otherwise a rate of `19` could match `190` in a contradictory page.
+  const words = /[\p{L}\p{N}]/u;
+  for (let from = 0; from <= visible.length; ) {
+    const at = visible.indexOf(fact, from);
+    if (at < 0) return false;
+    if (
+      (!words.test(fact[0]) || !words.test(visible[at - 1] ?? '')) &&
+      (!words.test(fact.at(-1)) || !words.test(visible[at + fact.length] ?? ''))
+    )
+      return true;
+    from = at + 1;
+  }
+  return false;
+}
+
+function canonicalPage(reply, entry, expectedData, source) {
+  if (reply.status !== 200 || reply.type !== 'text/html' || !source) return false;
+  const html = reply.bytes.toString('utf8').replace(/<!--[\s\S]*?-->/g, '');
+  const head = /<head\b[^>]*>([\s\S]*?)<\/head>/i.exec(html)?.[1] ?? '';
+  const links =
+    head
+      .replace(/<(script|style|title|template|noscript)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '')
+      .match(/<link\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi) ?? [];
+  const rel = (tag, value) => attr(tag, 'rel').toLowerCase().split(/\s+/).includes(value);
+  const targets = (tag, url) => {
+    const href = attr(tag, 'href').trim();
+    return href.length > 0 && new URL(href, entry.canonical).href === url;
+  };
+  const canonicalLinks = links.filter((tag) => rel(tag, 'canonical'));
+  if (canonicalLinks.length !== 1 || !targets(canonicalLinks[0], entry.canonical)) return false;
+
+  const body = /<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(html)?.[1];
+  if (body === undefined) return false;
+  const visible = textContent(body);
+  if (visible) {
+    const facts = source.markdown
+      .split(/\r?\n/)
+      .map((line) => line.replace(/^\s*(?:#{1,6}\s+|>\s*|[-*+]\s+|\d+\.\s+)/, '').trim())
+      .filter(Boolean);
+    if (
+      !facts.length ||
+      facts.some((line) => {
+        const text = line.replace(/\s+/g, ' ');
+        return (
+          !containsFact(visible, text) &&
+          !containsFact(visible, text.replace(/(\*\*|__|~~|`|\*)(.+?)\1/g, '$2'))
+        );
+      })
+    )
+      return false;
+  } else {
+    // A JS-only shell must point anonymous clients to the exact, byte-verified mirror.
+    if (
+      !links.some(
+        (tag) =>
+          rel(tag, 'alternate') &&
+          attr(tag, 'type').toLowerCase() === 'text/markdown' &&
+          targets(tag, entry.mirror),
+      ) ||
+      !(html.match(/<script\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi) ?? []).some((tag) =>
+        attr(tag, 'src').trim(),
+      )
+    )
+      return false;
+  }
+  if (!expectedData) return true;
+  for (const script of html.matchAll(/(<script\b[^>]*>)([\s\S]*?)<\/script>/gi)) {
+    if (attr(script[1], 'type').toLowerCase() !== 'application/ld+json') continue;
+    const data = JSON.parse(script[2]);
+    const nodes = Array.isArray(data) ? data : [data, ...(data?.['@graph'] ?? [])];
+    if (
+      nodes.some(
+        (node) => node && Object.entries(expectedData).every(([key, val]) => node[key] === val),
+      )
+    )
+      return true;
+  }
+  return false;
+}
+
+// Validate the entire probe list before making any request. A private or malformed
+// target must never appear in an error receipt, including the URL's userinfo.
+function probeTarget(probe, base) {
+  if (
+    !probe ||
+    typeof probe !== 'object' ||
+    Array.isArray(probe) ||
+    Object.keys(probe).some(
+      (key) => !['path', 'status', 'type', 'contains', 'excludes'].includes(key),
+    ) ||
+    typeof probe.path !== 'string' ||
+    !probe.path ||
+    /[?#\\\s]/u.test(probe.path) ||
+    probe.path.startsWith('//') ||
+    !Number.isInteger(probe.status) ||
+    probe.status < 100 ||
+    probe.status > 599 ||
+    (probe.type !== undefined &&
+      (typeof probe.type !== 'string' || !/^[\w.+-]+\/[\w.+-]+$/.test(probe.type)))
+  )
+    return null;
+  for (const list of [probe.contains, probe.excludes]) {
+    if (
+      list !== undefined &&
+      (!Array.isArray(list) || !list.every((s) => typeof s === 'string' && s.trim()))
+    )
+      return null;
+  }
+  try {
+    const url = new URL(probe.path, base);
+    if (
+      url.origin !== base.origin ||
+      url.username ||
+      url.password ||
+      !url.pathname.startsWith(base.pathname)
+    )
+      return null;
+    for (const part of probe.path.split('/')) {
+      const decoded = decodeURIComponent(part);
+      if (
+        decoded === '.' ||
+        decoded === '..' ||
+        /[\\/%?#\s]/u.test(decoded) ||
+        [...decoded].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)
+      )
+        return null;
+    }
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyPublication(plan, config, probes = {}, candidates = []) {
+  const base = new URL(config.siteUrl.replace(/\/?$/, '/'));
+  const checks = [];
+  if (
+    !probes ||
+    typeof probes !== 'object' ||
+    Array.isArray(probes) ||
+    Object.keys(probes).some((key) => key !== 'responses') ||
+    (probes.responses !== undefined && !Array.isArray(probes.responses))
+  )
+    return { status: 'failed', code: 'invalid-probe', checks };
+  const responses = probes.responses ?? [];
+  const targets = responses.map((probe) => probeTarget(probe, base));
+  if (targets.some((target) => !target)) return { status: 'failed', code: 'invalid-probe', checks };
+  async function check(url, test, inspect, identity = { url }) {
+    try {
+      const reply = await readResponse(url, base.origin);
+      const pass = Boolean(inspect(reply));
+      checks.push({ test, ...identity, pass, status: reply.status, type: reply.type });
+    } catch (error) {
+      checks.push({
+        test,
+        ...identity,
+        pass: false,
+        error: error.name === 'TimeoutError' ? 'timeout' : 'request-or-validation-failed',
+      });
+    }
+  }
+  if (!config.enabled || !plan.assets.length)
+    return { status: 'failed', code: 'no-active-publication', checks };
+  for (const asset of plan.assets) {
+    const expected = asset.mediaType.split(';')[0];
+    await check(new URL(asset.path, base).href, 'published-bytes', (r) => {
+      const type =
+        r.type === expected ||
+        (expected === 'text/markdown' && r.type === 'text/plain') ||
+        (expected === 'application/ld+json' && r.type === 'application/json');
+      return (
+        r.status === 200 &&
+        type &&
+        createHash('sha256').update(r.bytes).digest('hex') === asset.digest
+      );
+    });
+  }
+  const sources = new Map(candidates.map((source) => [source.id, source]));
+  for (const entry of plan.manifest.entries.filter((x) => x.status === 'included')) {
+    const data =
+      entry.structuredData &&
+      plan.assets.find((asset) => new URL(asset.path, base).href === entry.structuredData);
+    await check(entry.canonical, 'human-page', (r) =>
+      canonicalPage(r, entry, data ? JSON.parse(data.content) : null, sources.get(entry.sourceId)),
+    );
+  }
+  await check(
+    new URL(`agent-native/missing-${randomUUID()}.md`, base).href,
+    'missing-mirror',
+    (r) => r.status === 404 || r.status === 410,
+  );
+  for (const [index, probe] of responses.entries()) {
+    const url = targets[index];
+    await check(
+      url.href,
+      'declared-response',
+      (r) => {
+        const body = r.bytes.toString('utf8');
+        return (
+          r.status === probe.status &&
+          (!probe.type || r.type === probe.type) &&
+          (probe.contains ?? []).every(
+            (value) => typeof value === 'string' && value.length && body.includes(value),
+          ) &&
+          (probe.excludes ?? []).every(
+            (value) => typeof value === 'string' && value.length && !body.includes(value),
+          )
+        );
+      },
+      { probe: index + 1 },
+    );
+  }
+  return { status: checks.every((c) => c.pass) ? 'verified' : 'failed', checks };
+}

package/dist/adapters/zod.d.ts

@@ -0,0 +1,4 @@
+import * as z from 'zod';
+import { type SchemaPort } from '../core/schema.js';
+export declare function fromZod<Schema extends z.ZodType>(schema: Schema): SchemaPort<z.output<Schema>>;
+//# sourceMappingURL=zod.d.ts.map

package/dist/adapters/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../src/adapters/zod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAkC,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAMpF,wBAAgB,OAAO,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAgB9F"}

package/dist/adapters/zod.js

@@ -0,0 +1,20 @@
+import * as z from 'zod';
+import { cloneJsonValue } from '../core/schema.js';
+function isReadonlyArray(value) {
+    return Array.isArray(value);
+}
+export function fromZod(schema) {
+    return Object.freeze({
+        parse(input) {
+            return schema.parse(input);
+        },
+        toJSONSchema() {
+            const converted = cloneJsonValue(z.toJSONSchema(schema, { unrepresentable: 'throw' }), 'JSON Schema');
+            if (isReadonlyArray(converted) || converted === null || typeof converted !== 'object') {
+                throw new TypeError('Zod schema must convert to a JSON Schema object');
+            }
+            return converted;
+        },
+    });
+}
+//# sourceMappingURL=zod.js.map

package/dist/adapters/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../src/adapters/zod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,cAAc,EAAmC,MAAM,mBAAmB,CAAC;AAEpF,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,OAAO,CAA2B,MAAc;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,CAAC,KAAc;YAClB,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,YAAY;YACV,MAAM,SAAS,GAAc,cAAc,CACzC,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,EACpD,aAAa,CACd,CAAC;YACF,IAAI,eAAe,CAAC,SAAS,CAAC,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;gBACtF,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;YACzE,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/astro.d.ts

@@ -0,0 +1,13 @@
+import type { AstroIntegration } from 'astro';
+export type AgentNativeAstroOptions = {
+    /** Absolute path to an application-owned browser entry module. */
+    readonly browserEntry: string;
+    /** Allow Astro's server build mode when the project owns on-demand routes and an adapter. */
+    readonly mode?: 'static' | 'on-demand';
+};
+/**
+ * Injects an application-owned browser entry through Astro's supported Vite page-script hook.
+ * The application remains responsible for endpoint routes and an Astro server adapter.
+ */
+export declare function agentNativeAstro(options: AgentNativeAstroOptions): AstroIntegration;
+//# sourceMappingURL=astro.d.ts.map

package/dist/astro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"astro.d.ts","sourceRoot":"","sources":["../src/astro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAM9C,MAAM,MAAM,uBAAuB,GAAG;IACpC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAgDnF"}

package/dist/astro.js

@@ -0,0 +1,41 @@
+import { isAbsolute } from 'node:path';
+/**
+ * Injects an application-owned browser entry through Astro's supported Vite page-script hook.
+ * The application remains responsible for endpoint routes and an Astro server adapter.
+ */
+export function agentNativeAstro(options) {
+    if (!isAbsolute(options.browserEntry)) {
+        throw new TypeError('browserEntry must be an absolute filesystem path');
+    }
+    if (options.mode !== undefined && options.mode !== 'static' && options.mode !== 'on-demand') {
+        throw new TypeError('mode must be "static" or "on-demand"');
+    }
+    return {
+        name: '@uppercut-labs/agent-native',
+        hooks: {
+            'astro:config:setup': ({ config, injectScript, logger }) => {
+                if (config.output === 'server' && options.mode !== 'on-demand') {
+                    logger.warn('Agent Native Astro integration supports static output only; browser bootstrap was not injected.');
+                    return;
+                }
+                injectScript('page', `import ${JSON.stringify(options.browserEntry)};`);
+                logger.info(options.mode === 'on-demand'
+                    ? 'Agent Native browser bootstrap enabled for an on-demand Astro application.'
+                    : 'Agent Native browser bootstrap enabled for static output.');
+            },
+            'astro:config:done': ({ buildOutput, logger }) => {
+                if (buildOutput !== 'static' && options.mode !== 'on-demand') {
+                    logger.warn('Agent Native Astro integration is static-only; this integration does not provide a server adapter or server capability endpoint.');
+                    throw new Error('Use output: "static", or set mode: "on-demand" and provide an application-owned adapter.');
+                }
+                if (buildOutput === 'server') {
+                    logger.info('Agent Native allows on-demand output; application-owned routes and adapter configuration remain in control.');
+                }
+                else {
+                    logger.info('Agent Native Astro integration verified static output; this integration does not install a server adapter or create server endpoints.');
+                }
+            },
+        },
+    };
+}
+//# sourceMappingURL=astro.js.map

package/dist/astro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astro.js","sourceRoot":"","sources":["../src/astro.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAcvC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC5F,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACL,IAAI,EAAE,6BAA6B;QACnC,KAAK,EAAE;YACL,oBAAoB,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAsB,EAAQ,EAAE;gBACnF,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;oBAC/D,MAAM,CAAC,IAAI,CACT,iGAAiG,CAClG,CAAC;oBACF,OAAO;gBACT,CAAC;gBAED,YAAY,CAAC,MAAM,EAAE,UAAU,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;gBACxE,MAAM,CAAC,IAAI,CACT,OAAO,CAAC,IAAI,KAAK,WAAW;oBAC1B,CAAC,CAAC,4EAA4E;oBAC9E,CAAC,CAAC,2DAA2D,CAChE,CAAC;YACJ,CAAC;YACD,mBAAmB,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,EAAqB,EAAQ,EAAE;gBACxE,IAAI,WAAW,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;oBAC7D,MAAM,CAAC,IAAI,CACT,kIAAkI,CACnI,CAAC;oBACF,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;gBACJ,CAAC;gBAED,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;oBAC7B,MAAM,CAAC,IAAI,CACT,6GAA6G,CAC9G,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,IAAI,CACT,uIAAuI,CACxI,CAAC;gBACJ,CAAC;YACH,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,52 @@
+import type { AuthorizationPort, AuthorizationRequest, ExecutionCaller } from './core/executor.js';
+export type TrustedPrincipal = {
+    readonly issuer: string;
+    readonly subject: string;
+    readonly clientId: string;
+    readonly tenantId: string;
+    readonly audience: string;
+    readonly scopes: readonly string[];
+    readonly expiresAt: number;
+};
+export type GrantQuery = {
+    readonly issuer: string;
+    readonly subject: string;
+    readonly clientId: string;
+    readonly tenantId: string;
+    readonly applicationId: string;
+    readonly audience: string;
+    readonly policyRevision: string;
+};
+export type PersistedGrant = GrantQuery & {
+    readonly grantId: string;
+    readonly scopes: readonly string[];
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly revokedAt: number | null;
+};
+export interface GrantStorePort {
+    find(query: GrantQuery): Promise<readonly PersistedGrant[]>;
+    save(grant: PersistedGrant): Promise<void>;
+    revoke(grantId: string, revokedAt: number): Promise<boolean>;
+}
+export type GrantAuthorizationOptions = {
+    readonly principal: TrustedPrincipal | null;
+    readonly applicationId: string;
+    readonly audience: string;
+    readonly policyRevision: string;
+    readonly store?: GrantStorePort;
+    readonly now?: () => number;
+    readonly authorizeResource?: (request: AuthorizationRequest, principal: TrustedPrincipal) => boolean | Promise<boolean>;
+};
+export declare function executionCallerForPrincipal(principal: TrustedPrincipal): ExecutionCaller;
+export declare function hasGrantForScopes(options: {
+    readonly principal: TrustedPrincipal;
+    readonly applicationId: string;
+    readonly audience: string;
+    readonly policyRevision: string;
+    readonly store: GrantStorePort;
+    readonly requiredScopes: readonly string[];
+    readonly now?: () => number;
+}): Promise<boolean>;
+export declare function createGrantAuthorization(options: GrantAuthorizationOptions): AuthorizationPort;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

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

package/dist/auth.js

@@ -0,0 +1,128 @@
+function requiredString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(label + ' must be a non-empty string');
+    }
+}
+function validPrincipal(principal) {
+    return (typeof principal === 'object' &&
+        principal !== null &&
+        typeof principal.issuer === 'string' &&
+        principal.issuer.length > 0 &&
+        typeof principal.subject === 'string' &&
+        principal.subject.length > 0 &&
+        typeof principal.clientId === 'string' &&
+        principal.clientId.length > 0 &&
+        typeof principal.tenantId === 'string' &&
+        principal.tenantId.length > 0 &&
+        typeof principal.audience === 'string' &&
+        principal.audience.length > 0 &&
+        Array.isArray(principal.scopes) &&
+        principal.scopes.every((scope) => typeof scope === 'string' && scope.length > 0) &&
+        Number.isSafeInteger(principal.expiresAt) &&
+        principal.expiresAt > 0);
+}
+function authenticatedCaller(caller) {
+    if (!('subject' in caller) || !('scopes' in caller))
+        return null;
+    return { subject: caller.subject, scopes: caller.scopes };
+}
+function queryMatches(grant, query) {
+    return (grant.issuer === query.issuer &&
+        grant.subject === query.subject &&
+        grant.clientId === query.clientId &&
+        grant.tenantId === query.tenantId &&
+        grant.applicationId === query.applicationId &&
+        grant.audience === query.audience &&
+        grant.policyRevision === query.policyRevision);
+}
+export function executionCallerForPrincipal(principal) {
+    if (!validPrincipal(principal))
+        throw new TypeError('trusted principal is invalid');
+    return Object.freeze({
+        kind: 'authenticated',
+        subject: JSON.stringify([principal.issuer, principal.subject, principal.tenantId]),
+        scopes: Object.freeze([...principal.scopes]),
+        identity: Object.freeze({
+            issuer: principal.issuer,
+            subject: principal.subject,
+            tenantId: principal.tenantId,
+            clientId: principal.clientId,
+        }),
+    });
+}
+export async function hasGrantForScopes(options) {
+    const { principal } = options;
+    if (!validPrincipal(principal))
+        return false;
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const currentTime = now();
+    if (!Number.isSafeInteger(currentTime) ||
+        currentTime < 0 ||
+        principal.expiresAt <= currentTime ||
+        principal.audience !== options.audience ||
+        !options.requiredScopes.every((scope) => principal.scopes.includes(scope)))
+        return false;
+    const query = {
+        issuer: principal.issuer,
+        subject: principal.subject,
+        clientId: principal.clientId,
+        tenantId: principal.tenantId,
+        applicationId: options.applicationId,
+        audience: options.audience,
+        policyRevision: options.policyRevision,
+    };
+    const grants = await options.store.find(query);
+    return grants.some((grant) => queryMatches(grant, query) &&
+        grant.revokedAt === null &&
+        Number.isSafeInteger(grant.expiresAt) &&
+        grant.expiresAt > currentTime &&
+        Number.isSafeInteger(grant.issuedAt) &&
+        grant.issuedAt <= currentTime &&
+        Array.isArray(grant.scopes) &&
+        options.requiredScopes.every((scope) => grant.scopes.includes(scope)));
+}
+export function createGrantAuthorization(options) {
+    requiredString(options.applicationId, 'applicationId');
+    requiredString(options.audience, 'audience');
+    requiredString(options.policyRevision, 'policyRevision');
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const principal = options.principal;
+    if (principal !== null && !validPrincipal(principal))
+        throw new TypeError('trusted principal is invalid');
+    return Object.freeze({
+        async authorize(request) {
+            if (request.access.kind === 'public')
+                return request.risk === 'read';
+            if (principal === null ||
+                options.store === undefined ||
+                !validPrincipal(principal) ||
+                options.authorizeResource === undefined)
+                return false;
+            const caller = authenticatedCaller(request.caller);
+            if (caller === null)
+                return false;
+            const expectedSubject = JSON.stringify([
+                principal.issuer,
+                principal.subject,
+                principal.tenantId,
+            ]);
+            if (caller.subject !== expectedSubject ||
+                caller.scopes.length !== principal.scopes.length ||
+                !principal.scopes.every((scope) => caller.scopes.includes(scope)))
+                return false;
+            const hasGrant = await hasGrantForScopes({
+                principal,
+                applicationId: options.applicationId,
+                audience: options.audience,
+                policyRevision: options.policyRevision,
+                store: options.store,
+                requiredScopes: request.access.scopes,
+                now,
+            });
+            if (!hasGrant)
+                return false;
+            return await options.authorizeResource(request, principal);
+        },
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/browser.d.ts

@@ -0,0 +1,47 @@
+import { type CapabilityDefinition } from './core/contracts.js';
+import { type AuthorizationPort, type ExecutionCaller } from './core/executor.js';
+import type { CapabilityRegistry } from './core/registry.js';
+import { type CapabilitySurfaceExposure } from './discovery.js';
+export type WebMcpTool = {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly annotations?: Readonly<Record<string, boolean>>;
+    readonly execute: (input: unknown, options: {
+        readonly signal: AbortSignal;
+    }) => unknown | Promise<unknown>;
+};
+export interface WebMcpModelContext {
+    registerTool(tool: WebMcpTool, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+export type BrowserDocumentLike = Pick<Document, 'defaultView'> & {
+    readonly modelContext?: WebMcpModelContext;
+};
+export type BrowserExecutionContext = {
+    readonly caller: ExecutionCaller;
+    readonly authorization: AuthorizationPort;
+};
+export type BrowserAdapterOptions = {
+    readonly surfaceExposure?: CapabilitySurfaceExposure;
+    readonly canExpose?: (definition: CapabilityDefinition<unknown, unknown>) => boolean | Promise<boolean>;
+    readonly resolveExecutionContext?: () => BrowserExecutionContext | Promise<BrowserExecutionContext>;
+};
+export type BrowserSkippedTool = {
+    readonly capabilityId: string;
+    readonly reason: 'no-browser-binding' | 'ambiguous-browser-binding' | 'name-too-long' | 'policy-denied' | 'registration-failed';
+};
+export type BrowserSyncReport = {
+    readonly supported: boolean;
+    readonly registered: readonly string[];
+    readonly skipped: readonly BrowserSkippedTool[];
+};
+export interface BrowserCapabilityAdapter {
+    readonly supported: boolean;
+    sync(registry: CapabilityRegistry, options?: BrowserAdapterOptions): Promise<BrowserSyncReport>;
+    dispose(): void;
+}
+export declare function createBrowserCapabilityAdapter(document: BrowserDocumentLike): BrowserCapabilityAdapter;
+//# sourceMappingURL=browser.d.ts.map