apcore-a2a 0.5.0 → 0.7.0

package/README.md

@@ -32,6 +32,7 @@ Built on [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) and [Express
 - **JWT authentication** — tokens bridged to apcore's Identity context
 - **A2A Explorer UI** — browser UI for discovering and testing skills, with auth bar and cURL generation
 - **Built-in client** — `A2AClient` for calling remote A2A agents
+- **OpenAPI backend** — point the adapter at an OpenAPI 3.0/3.1 document and every operation becomes an A2A Skill, proxied over HTTP, with no apcore project on the other end
 - **CLI support** — `npx apcore-a2a serve` for zero-code startup
 - **Pluggable storage** — swap in Redis or PostgreSQL via the `TaskStore` interface
 - **Observability** — `/health`, `/metrics` endpoints
@@ -40,7 +41,15 @@ Built on [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) and [Express
 ## Requirements
 
 - Node.js >= 18.0.0
-- `apcore-js` >= 0.22.0
+- `apcore-js` >= 0.30.0
+- `apcore-toolkit` >= 0.11.1
+
+> **OpenAPI backend.** No extra install. The backend needs apcore-toolkit's
+> `OpenAPIScanner`, `loadSpec` and `HTTPProxyRegistryWriter`, all of which ship in
+> the `apcore-toolkit` dependency above and use the global `fetch` available on
+> Node 18+ — so this package declares no `openapi` optional dependency. (The
+> Python distribution declares an `apcore-a2a[openapi]` extra because there the
+> same three pieces sit behind `apcore-toolkit[http-proxy]`.)
 
 ---
 
@@ -80,6 +89,68 @@ npx apcore-a2a serve --extensions-dir ./extensions --port 3000 --explorer --metr
 npx apcore-a2a serve --extensions-dir ./extensions --auth-type bearer --auth-key mysecret
 ```
 
+### Serve an OpenAPI document as A2A Skills
+
+Point the adapter at an OpenAPI 3.0/3.1 document and every operation becomes a
+skill, proxied over HTTP to the API that published it. No apcore project required
+on the other end.
+
+```bash
+npx apcore-a2a serve \
+  --from-openapi https://petstore3.swagger.io/api/v3/openapi.json \
+  --openapi-prefix petstore \
+  --openapi-header "X-Api-Key: $PETSTORE_SPEC_KEY" \
+  --openapi-no-deprecated
+```
+
+```typescript
+import { openapiBackend, serve } from "apcore-a2a";
+
+const registry = await openapiBackend("https://api.example.com/openapi.json", {
+  prefix: "petstore",       // prepended to every derived module ID
+  baseUrl: "https://api.example.com", // defaults to servers[0].url
+  include: "pets\\..*",     // scanner filters
+  timeout: 30,              // SPEC-FETCH timeout, in SECONDS
+  headers: { "X-Api-Key": process.env.PETSTORE_SPEC_KEY! }, // spec fetch only
+  authHeaderFactory: () => ({ Authorization: `Bearer ${mintToken()}` }), // proxied calls
+});
+
+serve(registry);
+```
+
+Or configure it entirely through the Config Bus:
+
+```yaml
+apcore-a2a:
+  openapi:
+    spec: "https://api.example.com/openapi.json"  # URL, or a path resolved against Config.projectRoot
+    base_url: "https://api.example.com"
+    prefix: petstore
+    include: "pets.*"
+    exclude: "*.internal.*"
+    include_deprecated: false
+    acknowledge_unapproved_writes: false
+    timeout: 30.0            # spec fetch, seconds — never the per-call proxy timeout
+    headers:
+      X-Api-Key: "${PETSTORE_SPEC_KEY}"
+```
+
+Three things are worth knowing before pointing this at a production API:
+
+- **Write operations reach the PUBLIC Agent Card.** apcore-toolkit infers
+  annotations from the HTTP method and never infers `requiresApproval`, so a
+  `POST /charges` is annotated exactly like a `POST /echo` and appears on
+  `/.well-known/agent-card.json`, a route that is auth-exempt by design. The
+  backend logs a warning naming that exposure; close it with an ACL rule carrying
+  `approval: required` (which also withholds the skill from the public card), or
+  record the decision with `acknowledge_unapproved_writes: true`.
+- **`headers` authenticate the spec fetch only.** They are never forwarded to
+  proxied calls: a document is often public while the API behind it is not.
+  Per-request credentials belong in `authHeaderFactory`.
+- **ACL targets move when the upstream renames an operation.** Set `prefix` and
+  write the catch-all deny against the prefix (`targets: ["petstore.*"]`), not
+  against operation names.
+
 ### Call a remote A2A Agent
 
 Use the built-in client to discover and invoke any A2A-compliant agent:

package/dist/adapters/card-visibility.d.ts

@@ -0,0 +1,148 @@
+import type { AgentCard } from "@a2a-js/sdk";
+import { type Identity } from "apcore-js";
+import type { ModuleDescriptor } from "./skill-mapper.js";
+/**
+ * Agent Card skill visibility — who gets to see which skills.
+ *
+ * apcore's ACL is the authority on who may invoke what, and the discovery
+ * surface reflects that authority rather than ignoring it. Two surfaces, two
+ * answers:
+ *
+ * - the **public** card (srs FR-AGC-003) answers "what may *anyone* call": every
+ *   registered skill, minus apcore's reserved `system.*` management namespace,
+ *   minus those the ACL denies to the anonymous principal, minus those gated
+ *   behind a human. It resolves exactly one identity, so it is computed once when
+ *   the card is built. A per-caller filter here
+ *   would be strictly more accurate and unaffordable: `/.well-known/` is
+ *   auth-exempt by design, so every anonymous request would drive
+ *   `skills.length` calls into the consumer's ACL audit sink, each recording a
+ *   `deny` decision indistinguishable from a real enforcement event, at whatever
+ *   rate the client chooses.
+ *
+ * - the **extended** card (srs FR-AGC-004) answers "what may *you* call": the
+ *   ACL resolved against the authenticated identity, with `requires_approval`
+ *   skills restored — an approval gate is a prompt the caller can satisfy, not a
+ *   refusal. Affordable precisely because that endpoint requires credentials.
+ *
+ * Only the `system.*` subtraction is unconditional. Every other one is
+ * governance-shaped, and with no ACL configured they collapse: the ACL predicates
+ * are empty and the `requires_approval` annotation covers only
+ * `system.control.*`, leaving the six read modules to publish the deployment's
+ * module inventory, health and usage to any anonymous caller. `ACL.discover()`
+ * yields nothing for a missing root by design, so "no ACL at all" is the default
+ * rather than an edge case — which is why the rule that has to hold there keys on
+ * apcore's namespace and not on a governance verdict (srs FR-AGC-003 criteria 12
+ * and 13).
+ *
+ * Authorization and approval are two independent results, not one (apcore
+ * PROTOCOL_SPEC §6.1.6), and this module reads them apart. `ACL.check` folds
+ * them into a boolean that **fails closed** on an approval requirement —
+ * correct for a caller about to execute, wrong for a discovery surface, where it
+ * would delete a skill from the extended card for the one reason FR-AGC-004 says
+ * to keep it. `ACL.checkAccess` carries both axes, so `access` decides
+ * visibility and `approvalRequired` decides only whether the public card is the
+ * right surface.
+ *
+ * Before this module, this binding filtered nothing at all: `buildSkills`
+ * iterated `registry.list()` and never consulted the ACL, so a module the ACL
+ * denied to everyone was still advertised — by id, name, description and full
+ * input schema — to any anonymous caller.
+ *
+ * **Internal module.** The `export` keywords below are module visibility, not a
+ * public contract: `package.json` declares only `"."` in `exports`, so a
+ * consumer cannot deep-import this file at all, and nothing here appears in
+ * `docs/features/public-api.md`. The surface is expected to move —
+ * `allowedSkillIds` already changed meaning once (it now reports the
+ * authorization axis alone, where it used to fold in the approval gate). Depend
+ * on `serve` / `A2AServerFactory` instead.
+ */
+/**
+ * apcore's reserved namespace for the runtime's own management modules (apcore
+ * PROTOCOL_SPEC §6.7) — `system.health.*`, `system.usage.*`, `system.manifest.*`
+ * and, under the second opt-in, `system.control.*`. apcore identifies the
+ * surface by this prefix itself, in `Executor.governanceState()`, so matching on
+ * it conveys apcore's own boundary rather than inventing one.
+ */
+export declare const SYSTEM_NAMESPACE = "system.";
+/** Whether `skillId` is one of apcore's management modules. */
+export declare function isSystemSkill(skillId: string): boolean;
+/** The two axes of one ACL decision (apcore PROTOCOL_SPEC §6.8.1). */
+export interface AccessDecisionLike {
+    readonly access: "allow" | "deny";
+    readonly approvalRequired: boolean;
+}
+/** The minimum surface this module reads off an apcore ACL. */
+export interface AclLike {
+    check(callerId: string | null, targetId: string, context?: unknown): boolean;
+    checkAccess?(callerId: string | null, targetId: string, context?: unknown): AccessDecisionLike;
+}
+/** The minimum surface this module reads off an apcore Registry. */
+export interface RegistryLike {
+    list(): string[];
+    getDefinition(moduleId: string): ModuleDescriptor | null | undefined;
+}
+/**
+ * The apcore ACL backing `executor`, if one is configured.
+ *
+ * apcore-js exposes `setAcl` but no getter, so this reads the public property
+ * when one appears upstream and falls back to the private field. `null` means
+ * "no ACL configured", which is the common case and leaves every card
+ * unfiltered.
+ */
+export declare function executorAcl(executor: unknown): AclLike | null;
+/**
+ * The skills the ACL permits `identity` to invoke, each mapped to whether
+ * invoking it needs a human first.
+ *
+ * With no ACL configured every id is permitted and none is gated, which is what
+ * makes this free for the common single-tenant deployment.
+ *
+ * The ACL is consulted with **no arguments projection**, because a card is
+ * discovery and there is no call site yet. An `arguments` condition (§6.1.7) is
+ * therefore unevaluable, so a rule carrying one neither denies nor grants — but
+ * an `allow` rule's `approval: required` stays *pending* and composes with
+ * whatever grants (§6.1.1 rule 5). A skill gated only for some argument shapes
+ * thus reports `true` here: at discovery time "this may need approval" is the
+ * honest answer, and it is the one that keeps such a skill off the public card.
+ *
+ * `callerId` is left `null` deliberately. apcore defines it as the *calling
+ * module* in a nested call chain, managed by `Context.child`; a top-level
+ * inbound request has none, and the ACL maps `null` to `@external`. That is
+ * apcore's contract, not a gap — `callers: ["@external"]` is how an operator
+ * denies external access, and it has to keep matching an authenticated request
+ * or the rule silently stops covering the traffic it was written for. The
+ * authenticated principal travels in the context instead, where the
+ * `identityTypes` / `roles` conditions see it.
+ */
+export declare function skillAccess(executor: unknown, skillIds: readonly string[], identity: Identity | null): Map<string, boolean>;
+/**
+ * The subset of `skillIds` the ACL authorizes `identity` to invoke.
+ *
+ * The authorization axis alone: a skill the ACL allows but gates behind an
+ * approval is in this set, because the caller may reach it. Callers that also
+ * need the gate read {@link skillAccess}.
+ */
+export declare function allowedSkillIds(executor: unknown, skillIds: readonly string[], identity: Identity | null): Set<string>;
+/**
+ * The public card: what an unauthenticated caller could actually invoke.
+ *
+ * `system.*` is removed unconditionally (srs FR-AGC-003 criteria 12 and 13); the
+ * remaining subtractions are governance-shaped. See the module docstring for why
+ * this is resolved once rather than per caller.
+ */
+export declare function buildPublicCard(card: AgentCard, executor: unknown, registry: RegistryLike | null | undefined): AgentCard;
+/**
+ * The extended card: what the authenticated caller may invoke.
+ *
+ * `requires_approval` skills are kept (srs FR-AGC-004 criterion 2), whether the
+ * gate comes from the module's annotation or from an ACL rule. Only the
+ * authorization axis of the decision filters here — dropping a skill because it
+ * needs a human would report a refusal the ACL never issued.
+ *
+ * `system.*` is kept too (criterion 11), filtered by the ACL like any other
+ * skill: the namespace exclusion is a property of the public card, not of the
+ * skill, and an authenticated management agent the ACL permits must still be
+ * able to discover the surface it is entitled to drive.
+ */
+export declare function buildExtendedCard(card: AgentCard, executor: unknown, identity: Identity | null): AgentCard;
+//# sourceMappingURL=card-visibility.d.ts.map

package/dist/adapters/card-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-visibility.d.ts","sourceRoot":"","sources":["../../src/adapters/card-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7E,WAAW,CAAC,CACV,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,kBAAkB,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAQ7D;AA6CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,GAAG,CAAC,MAAM,CAAC,CAEb;AAOD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GACxC,SAAS,CAqBX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,SAAS,CAGX"}

package/dist/adapters/card-visibility.js

@@ -0,0 +1,237 @@
+import { Context } from "apcore-js";
+import { requiresApproval } from "./skill-mapper.js";
+/**
+ * Agent Card skill visibility — who gets to see which skills.
+ *
+ * apcore's ACL is the authority on who may invoke what, and the discovery
+ * surface reflects that authority rather than ignoring it. Two surfaces, two
+ * answers:
+ *
+ * - the **public** card (srs FR-AGC-003) answers "what may *anyone* call": every
+ *   registered skill, minus apcore's reserved `system.*` management namespace,
+ *   minus those the ACL denies to the anonymous principal, minus those gated
+ *   behind a human. It resolves exactly one identity, so it is computed once when
+ *   the card is built. A per-caller filter here
+ *   would be strictly more accurate and unaffordable: `/.well-known/` is
+ *   auth-exempt by design, so every anonymous request would drive
+ *   `skills.length` calls into the consumer's ACL audit sink, each recording a
+ *   `deny` decision indistinguishable from a real enforcement event, at whatever
+ *   rate the client chooses.
+ *
+ * - the **extended** card (srs FR-AGC-004) answers "what may *you* call": the
+ *   ACL resolved against the authenticated identity, with `requires_approval`
+ *   skills restored — an approval gate is a prompt the caller can satisfy, not a
+ *   refusal. Affordable precisely because that endpoint requires credentials.
+ *
+ * Only the `system.*` subtraction is unconditional. Every other one is
+ * governance-shaped, and with no ACL configured they collapse: the ACL predicates
+ * are empty and the `requires_approval` annotation covers only
+ * `system.control.*`, leaving the six read modules to publish the deployment's
+ * module inventory, health and usage to any anonymous caller. `ACL.discover()`
+ * yields nothing for a missing root by design, so "no ACL at all" is the default
+ * rather than an edge case — which is why the rule that has to hold there keys on
+ * apcore's namespace and not on a governance verdict (srs FR-AGC-003 criteria 12
+ * and 13).
+ *
+ * Authorization and approval are two independent results, not one (apcore
+ * PROTOCOL_SPEC §6.1.6), and this module reads them apart. `ACL.check` folds
+ * them into a boolean that **fails closed** on an approval requirement —
+ * correct for a caller about to execute, wrong for a discovery surface, where it
+ * would delete a skill from the extended card for the one reason FR-AGC-004 says
+ * to keep it. `ACL.checkAccess` carries both axes, so `access` decides
+ * visibility and `approvalRequired` decides only whether the public card is the
+ * right surface.
+ *
+ * Before this module, this binding filtered nothing at all: `buildSkills`
+ * iterated `registry.list()` and never consulted the ACL, so a module the ACL
+ * denied to everyone was still advertised — by id, name, description and full
+ * input schema — to any anonymous caller.
+ *
+ * **Internal module.** The `export` keywords below are module visibility, not a
+ * public contract: `package.json` declares only `"."` in `exports`, so a
+ * consumer cannot deep-import this file at all, and nothing here appears in
+ * `docs/features/public-api.md`. The surface is expected to move —
+ * `allowedSkillIds` already changed meaning once (it now reports the
+ * authorization axis alone, where it used to fold in the approval gate). Depend
+ * on `serve` / `A2AServerFactory` instead.
+ */
+/**
+ * apcore's reserved namespace for the runtime's own management modules (apcore
+ * PROTOCOL_SPEC §6.7) — `system.health.*`, `system.usage.*`, `system.manifest.*`
+ * and, under the second opt-in, `system.control.*`. apcore identifies the
+ * surface by this prefix itself, in `Executor.governanceState()`, so matching on
+ * it conveys apcore's own boundary rather than inventing one.
+ */
+export const SYSTEM_NAMESPACE = "system.";
+/** Whether `skillId` is one of apcore's management modules. */
+export function isSystemSkill(skillId) {
+    return skillId.startsWith(SYSTEM_NAMESPACE);
+}
+/**
+ * The apcore ACL backing `executor`, if one is configured.
+ *
+ * apcore-js exposes `setAcl` but no getter, so this reads the public property
+ * when one appears upstream and falls back to the private field. `null` means
+ * "no ACL configured", which is the common case and leaves every card
+ * unfiltered.
+ */
+export function executorAcl(executor) {
+    for (const key of ["acl", "_acl"]) {
+        const acl = executor?.[key];
+        if (acl && typeof acl.check === "function") {
+            return acl;
+        }
+    }
+    return null;
+}
+/**
+ * An apcore `Context` carrying `identity`, for conditional ACL rules.
+ *
+ * An ACL rule's `conditions` block (`identityTypes`, `roles`) is evaluated
+ * against the context, and the check returns false without one — so a card
+ * filtered with no context would hide every skill a conditional rule allows.
+ * Building the context the same way the executor does is what keeps the card and
+ * the call path agreeing about the same principal.
+ */
+function aclContext(identity) {
+    try {
+        // apcore-js `Context.create` takes positional arguments (identity first),
+        // unlike the Python binding's keyword form. Passing an options object here
+        // would silently produce a context with no identity, and every conditional
+        // rule would then evaluate false — hiding exactly the skills it allows.
+        return Context.create(identity);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `[authorized, approvalRequired]` for one skill, from apcore's ACL.
+ *
+ * Reads `checkAccess` (apcore-js >= 0.28.0, PROTOCOL_SPEC §6.8.1), which reports
+ * the two axes separately. The `check` fallback exists for an ACL that predates
+ * the accessor: there `approval` did not exist as a rule field, so `false` is
+ * not a guess but the only value such an ACL can mean — and a boolean that
+ * already fails closed degrades this surface toward showing less, never more.
+ */
+function decide(acl, callerId, skillId, ctx) {
+    if (typeof acl.checkAccess !== "function") {
+        return [acl.check(callerId, skillId, ctx), false];
+    }
+    const decision = acl.checkAccess(callerId, skillId, ctx);
+    return [decision.access === "allow", decision.approvalRequired === true];
+}
+/**
+ * The skills the ACL permits `identity` to invoke, each mapped to whether
+ * invoking it needs a human first.
+ *
+ * With no ACL configured every id is permitted and none is gated, which is what
+ * makes this free for the common single-tenant deployment.
+ *
+ * The ACL is consulted with **no arguments projection**, because a card is
+ * discovery and there is no call site yet. An `arguments` condition (§6.1.7) is
+ * therefore unevaluable, so a rule carrying one neither denies nor grants — but
+ * an `allow` rule's `approval: required` stays *pending* and composes with
+ * whatever grants (§6.1.1 rule 5). A skill gated only for some argument shapes
+ * thus reports `true` here: at discovery time "this may need approval" is the
+ * honest answer, and it is the one that keeps such a skill off the public card.
+ *
+ * `callerId` is left `null` deliberately. apcore defines it as the *calling
+ * module* in a nested call chain, managed by `Context.child`; a top-level
+ * inbound request has none, and the ACL maps `null` to `@external`. That is
+ * apcore's contract, not a gap — `callers: ["@external"]` is how an operator
+ * denies external access, and it has to keep matching an authenticated request
+ * or the rule silently stops covering the traffic it was written for. The
+ * authenticated principal travels in the context instead, where the
+ * `identityTypes` / `roles` conditions see it.
+ */
+export function skillAccess(executor, skillIds, identity) {
+    const access = new Map();
+    const acl = executorAcl(executor);
+    if (acl === null) {
+        for (const skillId of skillIds)
+            access.set(skillId, false);
+        return access;
+    }
+    const base = aclContext(identity);
+    for (const skillId of skillIds) {
+        const ctx = base && typeof base.child === "function"
+            ? base.child(skillId)
+            : undefined;
+        const callerId = ctx?.callerId ?? null;
+        try {
+            const [authorized, approvalRequired] = decide(acl, callerId, skillId, ctx);
+            if (authorized)
+                access.set(skillId, approvalRequired);
+        }
+        catch {
+            // A broken ACL must fail closed: serving MORE than the policy allows is
+            // the one outcome that cannot be walked back.
+            console.warn(`ACL check raised for skill ${skillId}; withholding it`);
+        }
+    }
+    return access;
+}
+/**
+ * The subset of `skillIds` the ACL authorizes `identity` to invoke.
+ *
+ * The authorization axis alone: a skill the ACL allows but gates behind an
+ * approval is in this set, because the caller may reach it. Callers that also
+ * need the gate read {@link skillAccess}.
+ */
+export function allowedSkillIds(executor, skillIds, identity) {
+    return new Set(skillAccess(executor, skillIds, identity).keys());
+}
+function withSkills(card, keep) {
+    const skills = (card.skills ?? []).filter((skill) => keep.has(skill.id));
+    return { ...card, skills };
+}
+/**
+ * The public card: what an unauthenticated caller could actually invoke.
+ *
+ * `system.*` is removed unconditionally (srs FR-AGC-003 criteria 12 and 13); the
+ * remaining subtractions are governance-shaped. See the module docstring for why
+ * this is resolved once rather than per caller.
+ */
+export function buildPublicCard(card, executor, registry) {
+    // The management namespace goes first and unconditionally: it is the only
+    // subtraction that survives a deployment with no ACL, and skipping the ACL for
+    // these ids also keeps `system.*` out of the audit trail of a decision whose
+    // answer cannot change the outcome.
+    const ids = (card.skills ?? [])
+        .map((skill) => skill.id)
+        .filter((id) => !isSystemSkill(id));
+    const access = skillAccess(executor, ids, null);
+    // Both sources of an approval gate, unioned as PROTOCOL_SPEC §6.9 composes
+    // them: the module's own annotation, and an ACL rule carrying
+    // `approval: required` for this principal. Since apcore 0.28.0 the annotation
+    // is one source among several, so reading it alone would leave a skill on the
+    // public card that an anonymous caller cannot in fact just call.
+    const keep = new Set();
+    for (const [skillId, approvalRequired] of access) {
+        if (approvalRequired)
+            continue;
+        if (registry && requiresApproval(registry.getDefinition(skillId)))
+            continue;
+        keep.add(skillId);
+    }
+    return withSkills(card, keep);
+}
+/**
+ * The extended card: what the authenticated caller may invoke.
+ *
+ * `requires_approval` skills are kept (srs FR-AGC-004 criterion 2), whether the
+ * gate comes from the module's annotation or from an ACL rule. Only the
+ * authorization axis of the decision filters here — dropping a skill because it
+ * needs a human would report a refusal the ACL never issued.
+ *
+ * `system.*` is kept too (criterion 11), filtered by the ACL like any other
+ * skill: the namespace exclusion is a property of the public card, not of the
+ * skill, and an authenticated management agent the ACL permits must still be
+ * able to discover the surface it is entitled to drive.
+ */
+export function buildExtendedCard(card, executor, identity) {
+    const ids = (card.skills ?? []).map((skill) => skill.id);
+    return withSkills(card, allowedSkillIds(executor, ids, identity));
+}
+//# sourceMappingURL=card-visibility.js.map

package/dist/adapters/card-visibility.js.map

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

package/dist/adapters/errors.d.ts

@@ -1,11 +1,41 @@
+/**
+ * A2A 1.0 `TaskNotFoundError`. Reserved for an unknown task id or one owned by
+ * another principal — deliberately indistinguishable from each other, and no
+ * longer produced for an authorization refusal (see {@link CODE_ACCESS_DENIED}).
+ */
+export declare const CODE_TASK_NOT_FOUND = -32001;
+export declare const CODE_ACCESS_DENIED = -32040;
+export declare const CODE_APPROVAL_DENIED = -32041;
+export declare const CODE_APPROVAL_TIMEOUT = -32042;
+/** Whether an apcore error code is one of the three governance refusals. */
+export declare function isGovernanceRefusal(code: string | undefined): boolean;
 export interface JsonRpcError {
     code: number;
     message: string;
 }
 export declare class ErrorMapper {
+    readonly discloseRefusalReason: boolean;
+    /**
+     * @param discloseRefusalReason Forward apcore's own message for the three
+     *   governance refusal codes instead of the fixed per-class string
+     *   (srs FR-ERR-011). Off by default. The code never changes with the flag —
+     *   what a refusal *is* does not depend on how much a deployment chooses to
+     *   say about it.
+     */
+    constructor(discloseRefusalReason?: boolean);
     /** ErrorFormatter interface for apcore ErrorFormatterRegistry. */
     format(error: unknown, _context?: unknown): Record<string, unknown>;
     toJsonRpcError(error: unknown): JsonRpcError;
+    /**
+     * Caller-facing message for a governance refusal.
+     *
+     * Default: the fixed per-class string. With `discloseRefusalReason`
+     * (srs FR-ERR-011): apcore's own message, through the same sanitizer every
+     * other forwarded message goes through. An empty or whitespace-only apcore
+     * message falls back to the fixed string rather than sending the caller
+     * nothing.
+     */
+    private refusalMessage;
     private handleApcoreError;
     private sanitizeMessage;
 }
@@ -42,13 +72,18 @@ export declare function isServerSideSchemaError(message: string): boolean;
  * {@link sanitizeMessage} does not strip (module ids, versions, env-var names,
  * hostnames). `userFixable` is also settable per-error by the module author,
  * which would let any module widen any fixed per-class string at will,
- * including the `ACL_DENIED` mask.
+ * including the governance refusals.
+ *
+ * The three governance codes (`ACL_DENIED`, `APPROVAL_DENIED`,
+ * `APPROVAL_TIMEOUT`) are in this partition only when `discloseRefusalReason` is
+ * set — the same flag the mapper branches on, so the two surfaces agree under
+ * either setting.
  *
  * `errorMapper message policy matches toJsonRpcError` locks this to the
- * branching in `ErrorMapper.handleApcoreError` across every apcore error code,
- * so the two cannot drift.
+ * branching in `ErrorMapper.handleApcoreError` across every apcore error code
+ * and both flag values, so the two cannot drift.
  */
-export declare function carriesCallerDetail(error: unknown): boolean;
+export declare function carriesCallerDetail(error: unknown, discloseRefusalReason?: boolean): boolean;
 /**
  * Strip file paths, traceback lines and excess whitespace from text bound for a
  * caller, then truncate to 500 characters. Module-level so the task-status

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IACtB,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKnE,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IAqB5C,OAAO,CAAC,iBAAiB;IA4DzB,OAAO,CAAC,eAAe;CAGxB;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAc1C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAC3C,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAiB5C,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IAQV,QAAQ,CAAC,qBAAqB,EAAE,OAAO;IAPnD;;;;;;OAMG;gBACkB,qBAAqB,GAAE,OAAe;IAE3D,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKnE,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IAqB5C;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,iBAAiB;IAmEzB,OAAO,CAAC,eAAe;CAGxB;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,qBAAqB,UAAQ,GAAG,OAAO,CAe1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD"}