@agentage/extension 0.2.1 → 0.3.0

package/dist/auth/part-auth.d.ts

@@ -0,0 +1,18 @@
+import { type Log } from '../log/log.js';
+import { type Env } from '../runtime/build-info.js';
+export declare const covers: (audience: string, host: string) => boolean;
+export declare const partAuth: (env: Env, id: string, log: Log, scopes: string[]) => Promise<{
+    tokenCheck: import("./token-check.js").TokenCheck;
+    resource: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+    };
+    checks: {
+        auth: import("../health/health.js").HealthCheck;
+    };
+}>;
+export declare const declaredScopes: (id: string, openapi: Record<string, unknown> | null, tools?: readonly {
+    scope: string;
+}[]) => string[];

package/dist/auth/part-auth.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { OriginSchema } from '../discovery/discovery.schema.js';
+import { messageOf } from '../log/log.js';
+import { formatIssues } from '../manifest/read-manifest.js';
+import {} from '../runtime/build-info.js';
+import { createRevokedList, REVOKED_POLL_MS } from './revoked.js';
+import { accessOfSecurity, scopeOf } from './token-check.js';
+import { createTokenCheck, remoteKeys } from './verify-token.js';
+// *.{a domain of two labels or more}, or one host, as a deployment's origin may name it.
+const isAudience = (audience) => {
+    const host = audience.startsWith('*.') ? audience.slice(2) : audience;
+    return ['https', 'http'].some((scheme) => OriginSchema.safeParse(`${scheme}://${host}`).success);
+};
+const AuthEnvSchema = z.object({
+    AGENTAGE_ISSUER: z
+        .url()
+        .refine((url) => URL.canParse(url) && new URL(url).origin === url, 'an origin, no path'),
+    AGENTAGE_AUDIENCE: z.string().refine(isAudience, '*.{domain} or one host'),
+    AGENTAGE_ORIGIN: z.url(),
+});
+// *.agentage.io covers the domain and every host under it at any depth; else one exact host.
+export const covers = (audience, host) => audience.startsWith('*.')
+    ? host === audience.slice(2) || host.endsWith(audience.slice(1))
+    : host === audience;
+const settingsOf = (env) => {
+    const parsed = AuthEnvSchema.safeParse(env);
+    if (!parsed.success)
+        throw new Error(`no token check, no start: ${formatIssues(parsed.error.issues)}`);
+    const { AGENTAGE_ISSUER: issuer, AGENTAGE_AUDIENCE: audience } = parsed.data;
+    const { origin, hostname } = new URL(parsed.data.AGENTAGE_ORIGIN);
+    if (!covers(audience, hostname))
+        throw new Error(`the host ${hostname} is not under the audience ${audience}`);
+    return { issuer, audience, origin };
+};
+// Keys and revoked list read once before the part serves; an issuer down at start is no stop.
+export const partAuth = async (env, id, log, scopes) => {
+    const { issuer, audience, origin } = settingsOf(env);
+    const { keys, read } = remoteKeys(issuer);
+    const revoked = createRevokedList(issuer, log);
+    const unread = (err) => log.warn('key set not read', { reason: messageOf(err) });
+    await Promise.all([read().catch(unread), revoked.refresh()]);
+    setInterval(() => void revoked.refresh(), REVOKED_POLL_MS).unref();
+    return {
+        tokenCheck: createTokenCheck({ issuer, audience, id, origin, keys, revoked }),
+        resource: {
+            resource: origin,
+            authorization_servers: [issuer],
+            scopes_supported: scopes,
+            bearer_methods_supported: ['header'],
+        },
+        checks: { auth: revoked.check },
+    };
+};
+export const declaredScopes = (id, openapi, tools = []) => {
+    const routes = Object.values(openapi?.['paths'] ?? {})
+        .flatMap((item) => Object.values(item))
+        .filter((op) => typeof op === 'object' && !Array.isArray(op))
+        .map((op) => scopeOf(id, accessOfSecurity(op.security ?? openapi?.['security'])));
+    const scopes = new Set([...routes, ...tools.map((tool) => tool.scope)]);
+    return [...scopes].filter((scope) => scope !== 'public').sort();
+};

package/dist/auth/revoked.d.ts

@@ -0,0 +1,9 @@
+import { type HealthCheck } from '../health/health.js';
+import { type Log } from '../log/log.js';
+export declare const REVOKED_POLL_MS = 30000;
+export declare const createRevokedList: (issuer: string, log: Log, now?: () => number) => {
+    has: (jti: string) => boolean;
+    loaded: () => boolean;
+    refresh: () => Promise<void>;
+    check: HealthCheck;
+};

package/dist/auth/revoked.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import {} from '../health/health.js';
+import { messageOf } from '../log/log.js';
+import { retryOnce } from './token-check.js';
+export const REVOKED_POLL_MS = 30_000;
+const STALE_MS = 5 * 60_000;
+const RevokedSchema = z.object({
+    revoked: z.array(z.object({ jti: z.string(), exp: z.number() })),
+    generatedAt: z.string(),
+});
+const readList = async (url) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok)
+        throw new Error(`the issuer answered ${res.status}`);
+    return new Set(RevokedSchema.parse(await res.json()).revoked.map((entry) => entry.jti));
+};
+// The issuer's revoked ids, read every 30 s so a revoke holds within 60 s (api-standards 5).
+export const createRevokedList = (issuer, log, now = Date.now) => {
+    let ids = new Set();
+    let readAt;
+    const refresh = async () => {
+        try {
+            ids = await retryOnce(() => readList(`${issuer}/.well-known/agentage-revoked`));
+            readAt = now();
+        }
+        catch (err) {
+            log.warn('revoked list not read', { reason: messageOf(err) });
+        }
+    };
+    const loaded = () => readAt !== undefined;
+    const fresh = () => readAt !== undefined && now() - readAt <= STALE_MS;
+    const check = async () => (fresh() ? 'ok' : 'degraded');
+    return { has: (jti) => ids.has(jti), loaded, refresh, check };
+};

package/dist/auth/route-access.js

@@ -1,21 +1,21 @@
-import { accessOfSecurity } from './token-check.js';
+import { accessOfSecurity, strongest } from './token-check.js';
 const PARAM = /^\{.+\}$/;
+// As Express routes: without case, and one trailing slash ignored.
 const sameShape = (template, path) => {
-    const want = template.split('/');
-    const got = path.split('/');
+    const want = template.toLowerCase().split('/');
+    const got = path
+        .toLowerCase()
+        .replace(/(.)\/$/, '$1')
+        .split('/');
     return want.length === got.length && want.every((seg, i) => PARAM.test(seg) || seg === got[i]);
 };
-const params = (template) => template.split('/').filter((seg) => PARAM.test(seg)).length;
-// As OpenAPI matches: a concrete path before a template, then the template with the fewest params.
-const mostSpecific = (templates, path) => templates
-    .filter((template) => sameShape(template, path))
-    .sort((a, b) => params(a) - params(b))[0];
-// The access the committed OpenAPI declares for a request: its operation's, else the document's.
+// The strongest access any matching operation declares: Express may run another path's handler.
 export const routeAccess = (doc, method, path) => {
     const paths = (doc?.['paths'] ?? {});
-    const template = mostSpecific(Object.keys(paths), path);
-    const operation = template ? paths[template]?.[method.toLowerCase()] : undefined;
-    if (!operation)
+    const operations = Object.keys(paths)
+        .filter((template) => sameShape(template, path))
+        .flatMap((template) => paths[template]?.[method.toLowerCase()] ?? []);
+    if (operations.length === 0)
         return 'read';
-    return accessOfSecurity(operation.security ?? doc?.['security']);
+    return strongest(operations.map((op) => accessOfSecurity(op.security ?? doc?.['security'])));
 };

package/dist/auth/token-check.d.ts

@@ -6,5 +6,8 @@ export interface Caller {
 export type TokenCheck = (authorization: string | undefined, access: Access) => Promise<Caller | null>;
 export declare const setCaller: (request: object, caller: Caller | null) => void;
 export declare const callerOf: (request: object) => Caller | null;
+export declare const RANK: Record<Access, number>;
+export declare const scopeOf: (id: string, access?: Access) => string;
 export declare const strongest: (needed: readonly Access[]) => Access;
 export declare const accessOfSecurity: (security: unknown) => Access;
+export declare const retryOnce: <T>(read: () => Promise<T>, retries?: (_err: unknown) => boolean) => Promise<T>;

package/dist/auth/token-check.js

@@ -1,8 +1,9 @@
-// Kit-private until ctx.auth.caller(request) exists (M3): part code never reads it from the request.
+import { setTimeout as sleep } from 'node:timers/promises';
 const callers = new WeakMap();
 export const setCaller = (request, caller) => void callers.set(request, caller);
 export const callerOf = (request) => callers.get(request) ?? null;
-const RANK = { public: 0, read: 1, write: 2, admin: 3 };
+export const RANK = { public: 0, read: 1, write: 2, admin: 3 };
+export const scopeOf = (id, access = 'read') => access === 'public' ? 'public' : `${id}:${access}`;
 export const strongest = (needed) => needed.reduce((top, access) => (RANK[access] > RANK[top] ? access : top), 'public');
 const VERB = /:(read|write|admin)$/;
 // OpenAPI security: [] is public, a scope names the verb; a route that declares nothing needs read.
@@ -16,3 +17,10 @@ export const accessOfSecurity = (security) => {
     const verbs = scopes.map((scope) => VERB.exec(scope)?.[1] ?? 'read');
     return verbs.length === 0 ? 'read' : strongest(verbs);
 };
+// security.md: a failed read of the issuer is tried once more before it counts as an outage.
+export const retryOnce = (read, retries = (_err) => true) => read().catch(async (err) => {
+    if (!retries(err))
+        throw err;
+    await sleep(1000);
+    return read();
+});

package/dist/auth/verify-token.d.ts

@@ -0,0 +1,18 @@
+import { type JWTVerifyGetKey } from 'jose';
+import { type TokenCheck } from './token-check.js';
+export interface TokenCheckDeps {
+    issuer: string;
+    audience: string;
+    id: string;
+    origin: string;
+    keys: JWTVerifyGetKey;
+    revoked: {
+        has(jti: string): boolean;
+        loaded(): boolean;
+    };
+}
+export declare const remoteKeys: (issuer: string) => {
+    keys: JWTVerifyGetKey<Uint8Array<ArrayBufferLike> | import("node:crypto").webcrypto.CryptoKey>;
+    read: () => Promise<void>;
+};
+export declare const createTokenCheck: (deps: TokenCheckDeps) => TokenCheck;

package/dist/auth/verify-token.js

@@ -0,0 +1,68 @@
+import { createRemoteJWKSet, errors, jwtVerify } from 'jose';
+import { z } from 'zod';
+import { fail, isFailure } from '../envelope/envelope.js';
+import { RANK, retryOnce, scopeOf } from './token-check.js';
+const VERIFY = { algorithms: ['EdDSA'], requiredClaims: ['exp'] };
+const ClaimsSchema = z.object({
+    sub: z.string().min(1),
+    aud: z.string(),
+    scope: z.string(),
+    jti: z.string().optional(),
+});
+const unavailable = (message) => fail('UNAVAILABLE', message, { retryAfter: 5 });
+const invalid = (origin, message = 'Invalid token') => fail('UNAUTHORIZED', message, {
+    headers: {
+        'WWW-Authenticate': `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
+    },
+});
+const forbidden = (scope) => fail('FORBIDDEN', `Needs ${scope}`, {
+    headers: { 'WWW-Authenticate': `Bearer error="insufficient_scope", scope="${scope}"` },
+});
+const outage = (err) => !(err instanceof errors.JWKSNoMatchingKey);
+// A key set that cannot be read is an outage, never a 401; a kid it lacks is a bad token.
+const keysOrOutage = (keys) => async (header, token) => {
+    if (!header.kid)
+        throw new errors.JWKSNoMatchingKey();
+    return retryOnce(async () => keys(header, token), outage).catch((err) => {
+        throw outage(err) ? unavailable('Token keys unavailable') : err;
+    });
+};
+// Read at start and again only for an unknown kid, so a known key outlives an issuer outage.
+export const remoteKeys = (issuer) => {
+    const set = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`), {
+        timeoutDuration: 3000,
+        cacheMaxAge: Infinity,
+    });
+    return { keys: keysOrOutage(set), read: () => retryOnce(set.reload) };
+};
+const claimsOf = async (authorization, deps) => {
+    const [scheme = '', credential = '', ...rest] = authorization.split(' ');
+    const bearer = scheme.toLowerCase() === 'bearer' && rest.length === 0;
+    const jwt = bearer && credential.startsWith('aga_') ? credential : '';
+    const options = { ...VERIFY, issuer: deps.issuer, audience: deps.audience };
+    const verified = await jwtVerify(jwt.slice(4), deps.keys, options).catch((err) => {
+        throw isFailure(err) ? err : invalid(deps.origin);
+    });
+    const claims = ClaimsSchema.safeParse(verified.payload);
+    if (!claims.success || verified.protectedHeader.typ !== 'at+jwt')
+        throw invalid(deps.origin);
+    return claims.data;
+};
+const grants = (scope, id, access) => {
+    const held = new Set(scope.split(' '));
+    return ['read', 'write', 'admin'].some((verb) => RANK[verb] >= RANK[access] && held.has(`${id}:${verb}`));
+};
+export const createTokenCheck = (deps) => async (authorization, access) => {
+    if (access === 'public')
+        return null;
+    if (!authorization)
+        throw invalid(deps.origin, 'Missing token');
+    const { sub, scope, jti } = await claimsOf(authorization, deps);
+    if (jti !== undefined && !deps.revoked.loaded())
+        throw unavailable('Revoked list unavailable');
+    if (jti !== undefined && deps.revoked.has(jti))
+        throw invalid(deps.origin, 'Token revoked');
+    if (!grants(scope, deps.id, access))
+        throw forbidden(scopeOf(deps.id, access));
+    return { sub, scopes: scope.split(' ') };
+};

package/dist/context/context.d.ts

@@ -1,3 +1,4 @@
+import { type Caller } from '../auth/token-check.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type Log } from '../log/log.js';
 import { type Store } from '../store/store.types.js';
@@ -12,6 +13,9 @@ export interface ExtensionInfo {
 }
 export interface PartContext {
     readonly extension: Readonly<ExtensionInfo>;
+    readonly auth: {
+        caller(request: object): Caller | null;
+    };
     readonly log: Log;
     readonly settings: Readonly<Record<string, SettingValue>>;
     readonly store: Store;

package/dist/context/context.js

@@ -1,3 +1,4 @@
+import { callerOf } from '../auth/token-check.js';
 import {} from '../manifest/manifest.schema.js';
 import { createLog } from '../log/log.js';
 import {} from '../store/store.types.js';
@@ -19,5 +20,6 @@ export const createContext = (input) => {
     });
     const log = input.log ?? createLog({ extension: pkg.agentage.id, part });
     const settings = Object.freeze({ ...settingDefaults(pkg), ...input.settings });
-    return Object.freeze({ extension, log, settings, store: store ?? NO_STORE });
+    const auth = Object.freeze({ caller: callerOf });
+    return Object.freeze({ extension, auth, log, settings, store: store ?? NO_STORE });
 };

package/dist/context/test-context.js

@@ -40,8 +40,11 @@ const serverContext = (options) => {
     const logs = [];
     const log = runLog(recordingLog(logs));
     const store = testStore(options.store, recordingLog([]));
+    const extension = { ...TEST_EXTENSION, ...options.extension };
+    const caller = { sub: 'usr_test', scopes: [`${extension.id}:read`] };
     return {
-        extension: { ...TEST_EXTENSION, ...options.extension },
+        extension,
+        auth: { caller: () => caller },
         log,
         logs,
         settings: { ...options.settings },

package/dist/discovery/discovery.d.ts

@@ -9,7 +9,10 @@ export type PartImages = Partial<Record<ImagePartKind, string>>;
 export declare const DEFAULT_RECORD_FILE = "/run/agentage/agentage-extension.json";
 export interface RecordExtras {
     openapi?: string;
-    tools?: string[];
+    tools?: {
+        name: string;
+        scope: string;
+    }[];
     widgets?: {
         name: string;
         element: string;
@@ -43,7 +46,10 @@ export declare const discoveryDocument: (record: ExtensionRecord, host: string)
         } | undefined;
     };
     openapi?: string | undefined;
-    tools?: string[] | undefined;
+    tools?: {
+        name: string;
+        scope: string;
+    }[] | undefined;
     widgets?: {
         name: string;
         element: string;

package/dist/discovery/discovery.schema.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare const OriginSchema: z.ZodString;
 export declare const WidgetSchema: z.ZodObject<{
     name: z.ZodString;
     element: z.ZodString;
@@ -35,7 +36,10 @@ export declare const ExtensionRecordSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strict>>>;
     widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         element: z.ZodString;
@@ -75,7 +79,10 @@ export declare const DiscoveryDocumentSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strict>>>;
     widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         element: z.ZodString;

package/dist/discovery/discovery.schema.js

@@ -20,7 +20,7 @@ const PartsRecordSchema = z
     .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
     message: 'at least one part with an image',
 });
-const OriginSchema = z
+export const OriginSchema = z
     .string()
     .max(270)
     .regex(/^(https:\/\/[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+|http:\/\/(127\.0\.0\.1|localhost))(:[0-9]{1,5})?$/);
@@ -29,6 +29,10 @@ export const WidgetSchema = z.strictObject({
     element: z.string().regex(/^[a-z][a-z0-9]*-[a-z0-9-]+$/),
     module: z.string().regex(/^\/ui\/[^/]+\/[^/]+\.m?js$/),
 });
+const ToolRecordSchema = z.strictObject({
+    name: PrefixedToolNameSchema,
+    scope: z.string().regex(/^(public|[a-z][a-z0-9-]*:(read|write|admin))$/),
+});
 const recordShape = {
     id: ExtensionIdSchema,
     version: VersionSchema,
@@ -39,7 +43,7 @@ const recordShape = {
         .string()
         .regex(/^\/api\/v[1-9][0-9]*\/openapi\.json$/)
         .optional(),
-    tools: z.array(PrefixedToolNameSchema).min(1).optional(),
+    tools: z.array(ToolRecordSchema).min(1).optional(),
     widgets: z.array(WidgetSchema).min(1).optional(),
     commands: z.array(CommandNameSchema).min(1).optional(),
 };

package/dist/envelope/envelope.d.ts

@@ -23,10 +23,12 @@ export interface Failure extends Error {
     readonly status: number;
     readonly details?: ErrorDetail[];
     readonly retryAfter?: number;
+    readonly headers?: Readonly<Record<string, string>>;
 }
 export interface FailOptions {
     details?: ErrorDetail[];
     retryAfter?: number;
+    headers?: Record<string, string>;
 }
 export declare const ok: <T>(data: T, meta?: Record<string, unknown>) => OkEnvelope<T>;
 export declare const fail: (code: ErrorCode, message: string, options?: FailOptions) => Failure;

package/dist/envelope/envelope.js

@@ -14,6 +14,7 @@ export const fail = (code, message, options = {}) => Object.assign(new Error(mes
     status: ERROR_STATUS[code],
     details: options.details,
     retryAfter: retryAfterOf(code, options.retryAfter),
+    headers: options.headers,
 });
 export const isFailure = (err) => err instanceof Error && err[FAILURE] === true;
 export const errorEnvelope = (failure, agcid) => {

package/dist/mcp/mcp-app.js

@@ -13,6 +13,7 @@ const MCP_CORS = {
     ...PUBLIC_CORS,
     allowedHeaders: [...PUBLIC_CORS.allowedHeaders, ...MCP_HEADERS],
 };
+const PARSE_ERROR = { jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null };
 const parsed = (body) => {
     try {
         return JSON.parse(body.toString('utf8'));
@@ -65,6 +66,9 @@ const send = async (response, res) => {
 const handle = (handler, options) => async (req, res) => {
     const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
     const message = parsed(body);
+    // The SDK reads a body again when given none (a BOM, say): it must only run what guard read.
+    if (message === undefined)
+        return void res.status(400).json(PARSE_ERROR);
     await guard(options, req, message);
     await send(await handler.fetch(webRequest(req, body), { parsedBody: message }), res);
 };

package/dist/mcp/server.js

@@ -4,7 +4,7 @@ import { currentAgcid } from '../agcid/current.js';
 import { fail, isFailure } from '../envelope/envelope.js';
 import {} from '../log/log.js';
 import { prefixed } from './tools.js';
-const text = (value) => [{ type: 'text', text: JSON.stringify(value) }];
+const text = (value) => [{ type: 'text', text: value }];
 // A failed tool is isError with the REST error shape; anything unexpected is a generic INTERNAL.
 // Outside a request (no agcid in scope) the error still carries a valid one, minted here.
 const errorResult = (err, log) => {
@@ -12,12 +12,24 @@ const errorResult = (err, log) => {
     if (failure.status >= 500)
         log.error(err);
     const error = { code: failure.code, message: failure.message, agcid: agcidOf(currentAgcid()) };
-    return { isError: true, content: text({ error }), structuredContent: { error } };
+    return { isError: true, content: text(error.message), structuredContent: { error } };
+};
+// The kit, not the SDK, refuses bad arguments (C7): the SDK lists the schema, passes all through.
+const listedOnly = (input) => ({
+    '~standard': { ...input['~standard'], validate: (value) => ({ value }) },
+});
+const argsOf = (entry, args) => {
+    const parsed = entry.spec.input.safeParse(args);
+    if (parsed.success)
+        return parsed.data;
+    const fields = new Set(parsed.error.issues.map((issue) => issue.path.join('.') || '(root)'));
+    throw fail('VALIDATION_ERROR', `Invalid arguments: ${[...fields].join(', ')}`);
 };
 const callback = (entry, log) => async (args) => {
     try {
-        const output = entry.spec.output.parse(await entry.handler(args));
-        return { content: text(output), structuredContent: output };
+        const output = entry.spec.output.parse(await entry.handler(argsOf(entry, args)));
+        const content = text(JSON.stringify(output));
+        return { content, structuredContent: output };
     }
     catch (err) {
         return errorResult(err, log);
@@ -29,7 +41,7 @@ export const serverFactory = (identity, tools, log) => () => {
     for (const entry of tools) {
         const config = {
             description: entry.spec.description,
-            inputSchema: entry.spec.input,
+            inputSchema: listedOnly(entry.spec.input),
             outputSchema: entry.spec.output,
         };
         server.registerTool(prefixed(identity.id, entry.name), config, callback(entry, log));

package/dist/runtime/part-runners.d.ts

@@ -11,6 +11,7 @@ export interface RunnerInput {
     env: Env;
     ctx: () => PartContext;
     base: PartAppBase;
+    openapi: Record<string, unknown> | null;
     importModule?: ImportModule;
 }
 export interface Running {

package/dist/runtime/part-runners.js

@@ -1,7 +1,6 @@
 import { join } from 'node:path';
 import {} from 'express';
 import {} from '../context/context.js';
-import { readOpenapi } from '../discovery/openapi.js';
 import {} from '../manifest/manifest.schema.js';
 import { loadCreate } from '../manifest/entry.js';
 import { hasPostgres } from '../manifest/parts.js';
@@ -20,8 +19,7 @@ import { createScheduler } from '../worker/scheduler.js';
 const callCreate = async (input, part, ctx) => (await loadCreate(input.dir, input.pkg, part, input.importModule))(ctx);
 const api = async (input) => {
     const router = (await callCreate(input, 'api', input.ctx()));
-    const openapi = await readOpenapi(input.dir);
-    return { app: createApiApp({ ...input.base, router, openapi }) };
+    return { app: createApiApp({ ...input.base, router, openapi: input.openapi }) };
 };
 const mcp = async (input) => {
     const registry = createToolRegistry();

package/dist/runtime/run-part.d.ts

@@ -1,5 +1,4 @@
 import { type Server } from 'node:http';
-import { type TokenCheck } from '../auth/token-check.js';
 import { type ImportModule } from '../manifest/entry.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
@@ -11,7 +10,6 @@ export interface RunPartOptions {
     env: Env;
     importModule?: ImportModule;
     serve?: Pick<ServeOptions, 'signals' | 'exit'>;
-    tokenCheck?: TokenCheck;
 }
 export declare const partOf: (pkg: ExtensionPackage, part: string) => ImagePartKind;
 export declare const runPart: (options: RunPartOptions) => Promise<Server>;

package/dist/runtime/run-part.js

@@ -2,14 +2,16 @@ import {} from 'node:http';
 import { createContext } from '../context/context.js';
 import { settingsFromEnv } from '../context/settings.js';
 import { DEFAULT_RECORD_FILE, loadRecord } from '../discovery/discovery.js';
-import {} from '../auth/token-check.js';
-import {} from '../health/health.js';
+import {} from '../discovery/discovery.schema.js';
+import { declaredScopes, partAuth } from '../auth/part-auth.js';
+import { readOpenapi } from '../discovery/openapi.js';
 import { createLog } from '../log/log.js';
 import {} from '../manifest/entry.js';
 import {} from '../manifest/manifest.schema.js';
 import { hasPostgres, imageParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { readManifest } from '../manifest/read-manifest.js';
+import {} from '../server/app.js';
 import { serve } from '../server/serve.js';
 import { createStore, storeCheck } from '../store/store.js';
 import {} from '../store/store.types.js';
@@ -48,28 +50,37 @@ const lazyContext = (start, store) => {
         return (ctx ??= contextFor(start, start.part, store));
     };
 };
-const baseFor = async (options, start, store) => {
+const guardFor = async (start, openapi, record) => {
+    if (start.part !== 'api' && start.part !== 'mcp')
+        return { checks: {} };
+    const { id } = start.pkg.agentage;
+    return partAuth(start.env, id, start.log, declaredScopes(id, openapi, record?.tools));
+};
+const baseFor = async (start, store, openapi) => {
     const { pkg, env, log } = start;
-    const checks = store ? { store: storeCheck(store) } : {};
+    const record = await recordFor(env, log);
+    const guard = await guardFor(start, openapi, record);
     return {
         pkg,
         log,
-        checks,
+        record,
+        ...guard,
+        checks: { ...(store ? { store: storeCheck(store) } : {}), ...guard.checks },
         build: buildInfoFromEnv(env),
-        record: await recordFor(env, log),
         origin: env['AGENTAGE_ORIGIN'] || undefined,
         ownImage: env['AGENTAGE_IMAGE'],
-        tokenCheck: options.tokenCheck,
     };
 };
 const inputFor = async (options, start) => {
     const store = storeFor(start);
+    const openapi = await readOpenapi(options.dir);
     return {
         dir: options.dir,
         pkg: start.pkg,
         env: start.env,
         ctx: lazyContext(start, store),
-        base: await baseFor(options, start, store),
+        base: await baseFor(start, store, openapi),
+        openapi,
         importModule: options.importModule,
     };
 };

package/dist/server/app.d.ts

@@ -18,6 +18,7 @@ export interface PartAppBase {
     origin?: string;
     checks?: Record<string, HealthCheck>;
     tokenCheck?: TokenCheck;
+    resource?: Record<string, unknown>;
 }
 export interface PartAppOptions extends PartAppBase {
     part: ImagePartKind;

package/dist/server/app.js

@@ -45,6 +45,9 @@ export const createPartApp = (options) => {
     if (options.part !== 'worker') {
         app.use('/.well-known', cors(PUBLIC_CORS));
         app.get('/.well-known/agentage-extension.json', discoveryHandler(options));
+        const { resource } = options;
+        if (resource)
+            app.get('/.well-known/oauth-protected-resource', (_req, res) => void res.json(resource));
     }
     options.mount(app);
     app.use(notFound);

package/dist/server/errors.js

@@ -25,5 +25,7 @@ export const errorHandler = (log) => (err, _req, res, _next) => {
         log.error(err);
     if (failure.retryAfter !== undefined)
         res.setHeader('Retry-After', String(failure.retryAfter));
+    for (const [name, value] of Object.entries(failure.headers ?? {}))
+        res.setHeader(name, value);
     res.status(failure.status).json(errorEnvelope(failure, agcidOfResponse(res)));
 };

package/dist/tool/record-extras.d.ts

@@ -1,4 +1,7 @@
 import { type RecordExtras } from '../discovery/discovery.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
-export declare const toolNames: (dir: string, pkg: ExtensionPackage) => Promise<string[]>;
+export declare const toolsOf: (dir: string, pkg: ExtensionPackage) => Promise<{
+    name: string;
+    scope: string;
+}[]>;
 export declare const recordExtras: (dir: string, pkg: ExtensionPackage) => Promise<RecordExtras>;

package/dist/tool/record-extras.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { z } from 'zod';
+import { scopeOf } from '../auth/token-check.js';
 import { createContext } from '../context/context.js';
 import {} from '../discovery/discovery.js';
 import { WidgetSchema } from '../discovery/discovery.schema.js';
@@ -19,8 +20,8 @@ const noStore = {
     },
 };
 const silent = createLog({ extension: 'build', part: 'mcp' }, () => undefined);
-// The tool names the mcp part registers, read by running its create(ctx) with a recording ctx.
-export const toolNames = async (dir, pkg) => {
+// The tools the mcp part registers and their scopes, read by running its create(ctx) on a recorder.
+export const toolsOf = async (dir, pkg) => {
     const registry = createToolRegistry();
     const base = createContext({
         pkg,
@@ -31,7 +32,11 @@ export const toolNames = async (dir, pkg) => {
         store: noStore,
     });
     await (await loadCreate(dir, pkg, 'mcp'))({ ...base, tool: registry.tool });
-    return registry.tools.map((tool) => prefixed(pkg.agentage.id, tool.name));
+    const { id } = pkg.agentage;
+    return registry.tools.map((tool) => ({
+        name: prefixed(id, tool.name),
+        scope: scopeOf(id, tool.spec.scope),
+    }));
 };
 const widgetsOf = async (dir) => {
     const value = await readJsonIfExists(join(dir, 'dist', 'ui', 'widgets.json'));
@@ -42,7 +47,7 @@ export const recordExtras = async (dir, pkg) => {
     const { code } = normalizeParts(pkg.agentage.parts);
     const extras = {};
     if (code.mcp) {
-        const tools = await toolNames(dir, pkg);
+        const tools = await toolsOf(dir, pkg);
         if (tools.length > 0)
             extras.tools = tools;
     }

package/dist/tool/up/compose.js

@@ -1,7 +1,7 @@
 import {} from '../../manifest/manifest.schema.js';
 import { hasPostgres, imageParts } from '../../manifest/parts.js';
 import {} from '../../manifest/primitives.schema.js';
-import { DEV_ISSUER } from './dev-issuer-app.js';
+import { DEV_AUDIENCE, DEV_ISSUER, UP_ISSUER } from './dev-issuer-app.js';
 import { GATEWAY_PORT, ISSUER_PORT, PART_PORT, TRAEFIK_COMMAND, TRAEFIK_IMAGE } from './gateway.js';
 export const STORE_IMAGE = 'postgres:18-alpine';
 const RECORD_TARGET = '/run/agentage/agentage-extension.json';
@@ -9,32 +9,40 @@ const ISSUER_ENTRY = 'node_modules/@agentage/extension/dist/tool/up/dev-issuer.j
 // A local-only credential: the store has no published port, only the parts' network reaches it.
 const STORE_PASSWORD = 'agentage-local';
 const storeUrl = (id) => `postgres://${id}:${STORE_PASSWORD}@store:5432/${id}`;
+const TOKENS = { AGENTAGE_ISSUER: UP_ISSUER, AGENTAGE_AUDIENCE: DEV_AUDIENCE };
 // Only the ui under `up` names the dev issuer: its CSP then lets the harness ask it for a token.
 const partEnv = (pkg, part) => ({
     AGENTAGE_ORIGIN: `http://localhost:${GATEWAY_PORT}`,
+    ...TOKENS,
     AGENTAGE_RECORD_FILE: RECORD_TARGET,
     ...(hasPostgres(pkg) && part !== 'ui' ? { AGENTAGE_STORE_URL: storeUrl(pkg.agentage.id) } : {}),
     ...(part === 'ui' ? { AGENTAGE_DEV_ISSUER: DEV_ISSUER } : {}),
 });
+const QUICK_CHECK = { interval: '2s', timeout: '3s', retries: 30 };
 const storeService = (id) => ({
     image: STORE_IMAGE,
     environment: { POSTGRES_USER: id, POSTGRES_PASSWORD: STORE_PASSWORD, POSTGRES_DB: id },
     volumes: ['store:/var/lib/postgresql'],
     healthcheck: {
         test: ['CMD-SHELL', `pg_isready -U ${id} -d ${id}`],
-        interval: '2s',
-        timeout: '3s',
-        retries: 30,
+        ...QUICK_CHECK,
     },
 });
-const partService = (input, part) => ({
-    image: input.tags[part],
-    environment: partEnv(input.pkg, part),
-    volumes: [`${input.recordFile}:${RECORD_TARGET}:ro`],
-    ...(hasPostgres(input.pkg) && part !== 'ui'
-        ? { depends_on: { store: { condition: 'service_healthy' } } }
-        : {}),
+const HEALTHY = { condition: 'service_healthy' };
+// api and mcp read the issuer's keys and revoked list before they serve.
+const dependsOn = (pkg, part) => ({
+    ...(hasPostgres(pkg) && part !== 'ui' ? { store: HEALTHY } : {}),
+    ...(part === 'api' || part === 'mcp' ? { issuer: HEALTHY } : {}),
 });
+const partService = (input, part) => {
+    const depends_on = dependsOn(input.pkg, part);
+    return {
+        image: input.tags[part],
+        environment: partEnv(input.pkg, part),
+        volumes: [`${input.recordFile}:${RECORD_TARGET}:ro`],
+        ...(Object.keys(depends_on).length > 0 ? { depends_on } : {}),
+    };
+};
 const fixedServices = (input, anyImage) => ({
     gateway: {
         image: TRAEFIK_IMAGE,
@@ -43,9 +51,7 @@ const fixedServices = (input, anyImage) => ({
         volumes: [`${input.gatewayFile}:/etc/traefik/dynamic.yml:ro`],
         healthcheck: {
             test: ['CMD', 'wget', '-qO-', 'http://127.0.0.1:8082/ping'],
-            interval: '2s',
-            timeout: '3s',
-            retries: 30,
+            ...QUICK_CHECK,
         },
     },
     issuer: {
@@ -59,7 +65,7 @@ const migrateService = (input) => ({
     command: ['node', 'dist/store/migrate.js'],
     environment: partEnv(input.pkg, 'migrate'),
     ...(input.seedsDir ? { volumes: [`${input.seedsDir}:/app/seeds:ro`] } : {}),
-    depends_on: { store: { condition: 'service_healthy' } },
+    depends_on: { store: HEALTHY },
     profiles: ['jobs'],
     restart: 'no',
 });

package/dist/tool/up/dev-issuer-app.d.ts

@@ -2,11 +2,17 @@ import { type KeyObject } from 'node:crypto';
 import { type Server } from 'node:http';
 import { z } from 'zod';
 export declare const DEV_ISSUER = "http://localhost:4281";
-export declare const DEV_AUDIENCE = "*.agentage.io";
+export declare const UP_ISSUER = "http://issuer:3000";
+export declare const DEV_AUDIENCE = "localhost";
+export type IssuerSettings = {
+    issuer: string;
+    audience: string;
+};
 declare const TokenRequestSchema: z.ZodObject<{
     scope: z.ZodString;
     sub: z.ZodOptional<z.ZodString>;
     ttlSeconds: z.ZodOptional<z.ZodInt>;
+    aud: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 interface Keys {
     kid: string;
@@ -14,9 +20,9 @@ interface Keys {
     jwk: Record<string, unknown>;
 }
 export declare const newKeys: () => Keys;
-export declare const mint: (keys: Keys, request: z.infer<typeof TokenRequestSchema>, now?: number) => {
+export declare const mint: (keys: Keys, request: z.infer<typeof TokenRequestSchema>, settings: IssuerSettings, now?: number) => {
     token: string;
     expiresAt: string;
 };
-export declare const createIssuer: (keys?: Keys) => Server;
+export declare const createIssuer: (settings?: IssuerSettings, keys?: Keys) => Server;
 export {};

package/dist/tool/up/dev-issuer-app.js

@@ -1,8 +1,12 @@
 import { generateKeyPairSync, randomUUID, sign } from 'node:crypto';
 import { createServer } from 'node:http';
 import { z } from 'zod';
+import { GATEWAY_PORT, PART_PORT } from './gateway.js';
+// Where the host reaches the dev issuer; the parts of `up` reach it, and tokens name it, by service.
 export const DEV_ISSUER = 'http://localhost:4281';
-export const DEV_AUDIENCE = '*.agentage.io';
+export const UP_ISSUER = `http://issuer:${PART_PORT}`;
+// The host of `up` (http://localhost:4280): the one host this audience covers.
+export const DEV_AUDIENCE = 'localhost';
 const TokenRequestSchema = z.strictObject({
     scope: z
         .string()
@@ -12,8 +16,10 @@ const TokenRequestSchema = z.strictObject({
         .string()
         .regex(/^[A-Za-z0-9_-]{1,64}$/)
         .optional(),
-    ttlSeconds: z.int().min(60).max(86_400).optional(),
+    ttlSeconds: z.int().min(1).max(86_400).optional(),
+    aud: z.string().min(1).max(253).optional(),
 });
+const RevokeSchema = z.strictObject({ jti: z.string().regex(/^tok_[0-9a-f-]{36}$/) });
 export const newKeys = () => {
     const { privateKey, publicKey } = generateKeyPairSync('ed25519');
     const kid = `dev-${randomUUID().slice(0, 8)}`;
@@ -25,18 +31,11 @@ export const newKeys = () => {
 };
 const b64 = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
 // The api-standards token shape: aga_<jwt>, typ at+jwt, EdDSA, scope {id}:{verb}, a jti.
-export const mint = (keys, request, now = Date.now()) => {
+export const mint = (keys, request, settings, now = Date.now()) => {
     const iat = Math.floor(now / 1000);
     const exp = iat + (request.ttlSeconds ?? 3600);
-    const claims = {
-        iss: DEV_ISSUER,
-        sub: request.sub ?? 'usr_dev',
-        aud: DEV_AUDIENCE,
-        scope: request.scope,
-        iat,
-        exp,
-        jti: `tok_${randomUUID()}`,
-    };
+    const { scope, sub = 'usr_dev', aud = settings.audience } = request;
+    const claims = { iss: settings.issuer, sub, aud, scope, iat, exp, jti: `tok_${randomUUID()}` };
     const input = `${b64({ alg: 'EdDSA', typ: 'at+jwt', kid: keys.kid })}.${b64(claims)}`;
     const signature = sign(null, Buffer.from(input), keys.privateKey).toString('base64url');
     return { token: `aga_${input}.${signature}`, expiresAt: new Date(exp * 1000).toISOString() };
@@ -46,7 +45,7 @@ const reply = (res, status, body) => {
         'content-type': 'application/json',
         'cache-control': 'no-store',
         'access-control-allow-origin': '*',
-        'access-control-allow-headers': 'content-type',
+        'access-control-allow-headers': 'content-type, x-client-type',
         'access-control-allow-methods': 'GET, POST, OPTIONS',
     });
     res.end(body === undefined ? undefined : JSON.stringify(body));
@@ -59,22 +58,52 @@ const readBody = async (req) => {
         throw new Error('body too large');
     return JSON.parse(text || '{}');
 };
-const tokenRoute = async (keys, req, res) => {
+const tokenRoute = async (issuer, req, res) => {
     const parsed = TokenRequestSchema.safeParse(await readBody(req).catch(() => null));
     if (!parsed.success)
         return reply(res, 400, { error: 'scope must be {id}:{read|write|admin}, space-separated' });
-    reply(res, 200, mint(keys, parsed.data));
+    reply(res, 200, mint(issuer.keys, parsed.data, issuer.settings));
+};
+// Kept for a day, the longest a dev token lives, so an entry never outlasts its token by more.
+const revokeRoute = async (issuer, req, res) => {
+    const parsed = RevokeSchema.safeParse(await readBody(req).catch(() => null));
+    if (!parsed.success)
+        return reply(res, 400, { error: 'jti must be a tok_ id' });
+    issuer.revoked.set(parsed.data.jti, Math.floor(Date.now() / 1000) + 86_400);
+    reply(res, 200, { jti: parsed.data.jti, revoked: true });
+};
+const revokedList = ({ revoked }) => {
+    const now = Date.now() / 1000;
+    const live = [...revoked].filter(([, exp]) => exp > now).map(([jti, exp]) => ({ jti, exp }));
+    return { revoked: live, generatedAt: new Date().toISOString() };
 };
-// Mints only: the kit does not verify tokens yet. Never part of a deployed estate.
-export const createIssuer = (keys = newKeys()) => createServer((req, res) => {
-    const path = (req.url ?? '/').split('?')[0];
+// security.md, local daemons: its tokens open the parts of `up`, so no other site may mint one.
+const ORIGINS = ['localhost', '127.0.0.1'].map((host) => `http://${host}:${GATEWAY_PORT}`);
+const allowed = ({ settings }, req) => {
+    const host = (req.headers.host ?? '').replace(/:[0-9]+$/, '');
+    const origin = req.headers.origin;
+    const hosts = ['localhost', '127.0.0.1', new URL(settings.issuer).hostname];
+    return hosts.includes(host) && (origin === undefined || ORIGINS.includes(origin));
+};
+const route = (issuer, req, res) => {
+    const at = `${req.method ?? ''} ${(req.url ?? '/').split('?')[0] ?? ''}`;
+    if (!allowed(issuer, req))
+        return reply(res, 403, { error: 'host or origin not allowed' });
     if (req.method === 'OPTIONS')
         return reply(res, 204, undefined);
-    if (req.method === 'GET' && path === '/health')
+    if (at === 'GET /health')
         return reply(res, 200, { status: 'ok' });
-    if (req.method === 'GET' && path === '/.well-known/jwks.json')
-        return reply(res, 200, { keys: [keys.jwk] });
-    if (req.method === 'POST' && path === '/token')
-        return void tokenRoute(keys, req, res);
+    if (at === 'GET /.well-known/jwks.json')
+        return reply(res, 200, { keys: [issuer.keys.jwk] });
+    if (at === 'GET /.well-known/agentage-revoked')
+        return reply(res, 200, revokedList(issuer));
+    if (at === 'POST /token')
+        return void tokenRoute(issuer, req, res);
+    if (at === 'POST /revoke')
+        return void revokeRoute(issuer, req, res);
     reply(res, 404, { error: 'not found' });
-});
+};
+export const createIssuer = (settings = { issuer: UP_ISSUER, audience: DEV_AUDIENCE }, keys = newKeys()) => {
+    const issuer = { settings, keys, revoked: new Map() };
+    return createServer((req, res) => route(issuer, req, res));
+};

package/dist/tool/up/local-record.d.ts

@@ -33,7 +33,10 @@ export declare const writeLocalRecord: (dir: string, pkg: ExtensionPackage, buil
             } | undefined;
         };
         openapi?: string | undefined;
-        tools?: string[] | undefined;
+        tools?: {
+            name: string;
+            scope: string;
+        }[] | undefined;
         widgets?: {
             name: string;
             element: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/extension",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The agentage extension kit: create(ctx) per part (pages, ui, api, mcp, worker, cli), the store, /health, discovery, the envelope, and the build tool with up and token",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,7 @@
     "@modelcontextprotocol/server": "^2.4.0",
     "cors": "^2.8.5",
     "helmet": "^8.1.0",
+    "jose": "^6.2.15",
     "pg": "^8.23.1",
     "zod": "^4.2.0"
   },

package/schemas/extension-discovery.schema.json

@@ -128,9 +128,23 @@
       "minItems": 1,
       "type": "array",
       "items": {
-        "type": "string",
-        "maxLength": 64,
-        "pattern": "^[a-z][a-z0-9-]*__[a-z][a-z0-9_-]*$"
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 64,
+            "pattern": "^[a-z][a-z0-9-]*__[a-z][a-z0-9_-]*$"
+          },
+          "scope": {
+            "type": "string",
+            "pattern": "^(public|[a-z][a-z0-9-]*:(read|write|admin))$"
+          }
+        },
+        "required": [
+          "name",
+          "scope"
+        ],
+        "additionalProperties": false
       }
     },
     "widgets": {

package/schemas/extension-record.schema.json

@@ -128,9 +128,23 @@
       "minItems": 1,
       "type": "array",
       "items": {
-        "type": "string",
-        "maxLength": 64,
-        "pattern": "^[a-z][a-z0-9-]*__[a-z][a-z0-9_-]*$"
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 64,
+            "pattern": "^[a-z][a-z0-9-]*__[a-z][a-z0-9_-]*$"
+          },
+          "scope": {
+            "type": "string",
+            "pattern": "^(public|[a-z][a-z0-9-]*:(read|write|admin))$"
+          }
+        },
+        "required": [
+          "name",
+          "scope"
+        ],
+        "additionalProperties": false
       }
     },
     "widgets": {