@auctra/sdk 0.7.18 → 0.7.19

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.7.19
+
+**Interop — OpenAPI catalog ingest is untrusted discovery**
+
+- `ingestOpenApiDocument` / `discoveryGrantsAuthority` for integrator apps.
+- Spec prose and `securitySchemes` are not grants. Mapping is an explicit table only.
+- Does not call Cloud and does not store catalogs.
+
 ## 0.7.18
 
 **Security — bind lease consume to the evaluated request fingerprint**

package/README.md

@@ -42,6 +42,9 @@ auctra.listPolicyTemplates() / applyPolicyTemplate()  # Pro+
 auctra.approveActionRequest() / rejectActionRequest() / escalateActionRequest()  # admin API key
 
 auctra.evidence.verify()
+
+ingestOpenApiDocument()     # local, untrusted catalog → capability records
+discoveryGrantsAuthority()  # always false
 ```
 
 API keys are **created in the console only** (`listApiKeys` is available in the SDK). Approvals via SDK require an **admin** key (not write-only).

package/dist/cjs/capability.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Vendor-neutral OpenAPI ingest for integrator apps.
+ * Catalog membership is not a grant. Mapping is an explicit table only.
+ * Keep behavior aligned with @auctra/authority-protocol capability.openapi.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPENAPI_OPERATION_MAP = exports.INTEROP_CONTRACT_VERSION = exports.CAPABILITY_FORMAT = exports.OPENAPI_ADAPTER_ID = void 0;
+exports.discoveryGrantsAuthority = discoveryGrantsAuthority;
+exports.ingestOpenApiDocument = ingestOpenApiDocument;
+exports.OPENAPI_ADAPTER_ID = "auctra.openapi-catalog.v0.1";
+exports.CAPABILITY_FORMAT = "auctra-capability.v0.1";
+exports.INTEROP_CONTRACT_VERSION = "0.1";
+exports.DEFAULT_OPENAPI_OPERATION_MAP = {
+    createTransfer: "send_payment",
+    listTransfers: "read_sensitive_data",
+};
+/** Catalog rows never grant Auctra authority. */
+function discoveryGrantsAuthority(_record) {
+    return false;
+}
+function issue(code, message) {
+    return { code, message };
+}
+/**
+ * Ingest an OpenAPI 3 document as untrusted capability metadata.
+ * Does not call Auctra Cloud. Does not grant authority.
+ */
+function ingestOpenApiDocument(doc, opts = {}) {
+    const openapi = typeof doc.openapi === "string" ? doc.openapi : "";
+    if (!openapi.startsWith("3.")) {
+        return { ok: false, issues: [issue("not_openapi3", "Only OpenAPI 3.x documents are accepted")] };
+    }
+    const paths = doc.paths;
+    if (!paths || typeof paths !== "object" || Array.isArray(paths)) {
+        return { ok: false, issues: [issue("missing_paths", "OpenAPI document has no paths object")] };
+    }
+    const at = opts.at ?? new Date();
+    const source_system = opts.source_system ?? exports.OPENAPI_ADAPTER_ID;
+    const provider = opts.provider ?? "openapi";
+    const service_id = opts.service_id ?? "imported-api";
+    const operationMap = opts.operationMap ?? exports.DEFAULT_OPENAPI_OPERATION_MAP;
+    const info = doc.info && typeof doc.info === "object" ? doc.info : {};
+    const infoBlurb = [info.description, info.title].filter((row) => typeof row === "string").join(" ");
+    const records = [];
+    const warnings = [];
+    const methods = ["get", "post", "put", "patch", "delete", "head", "options"];
+    for (const [path, item] of Object.entries(paths)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const pathItem = item;
+        for (const method of methods) {
+            const op = pathItem[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const operationId = typeof op.operationId === "string" && op.operationId.trim()
+                ? op.operationId.trim()
+                : `${method}:${path}`;
+            const untrusted = [op.summary, op.description, infoBlurb]
+                .filter((row) => typeof row === "string")
+                .join("\n");
+            if (/ignore previous|you are now|grant authority/i.test(untrusted)) {
+                warnings.push(issue("untrusted_instruction", "Description looks like an instruction; stored as untrusted text only"));
+            }
+            const mappedName = operationMap[operationId];
+            records.push({
+                format: exports.CAPABILITY_FORMAT,
+                interop_contract_version: exports.INTEROP_CONTRACT_VERSION,
+                state: mappedName ? "mapped" : "validated",
+                source_system,
+                source_record_id: `${method}:${path}`,
+                provider,
+                service_id,
+                operation_id: operationId,
+                invocation_type: "http",
+                http_method: method.toUpperCase(),
+                path,
+                declared_auth: Array.isArray(op.security) ? ["openapi-security"] : undefined,
+                retrieved_at: at.toISOString(),
+                auctra_operation_id: mappedName,
+                mapping_confidence: mappedName ? "high" : "unresolved",
+                untrusted_description: untrusted || undefined,
+            });
+        }
+    }
+    if (!records.length) {
+        return { ok: false, issues: [issue("empty", "OpenAPI document produced no operations")] };
+    }
+    return { ok: true, records, warnings };
+}

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withExecutionLease = exports.assertAuthorityLive = exports.assertAllowed = exports.onAllowed = exports.Auctra = exports.verifyDecisionArtifact = exports.verifyMandateArtifact = exports.AuctraApiError = exports.DEFAULT_BASE_URL = exports.AUCTRA_SDK_VERSION = void 0;
+exports.ingestOpenApiDocument = exports.discoveryGrantsAuthority = exports.OPENAPI_ADAPTER_ID = exports.INTEROP_CONTRACT_VERSION = exports.DEFAULT_OPENAPI_OPERATION_MAP = exports.CAPABILITY_FORMAT = exports.withExecutionLease = exports.assertAuthorityLive = exports.assertAllowed = exports.onAllowed = exports.Auctra = exports.verifyDecisionArtifact = exports.verifyMandateArtifact = exports.AuctraApiError = exports.DEFAULT_BASE_URL = exports.AUCTRA_SDK_VERSION = void 0;
 /**
  * @auctra/sdk — Stage 1.0 public surface.
  *
@@ -21,3 +21,10 @@ Object.defineProperty(exports, "onAllowed", { enumerable: true, get: function ()
 Object.defineProperty(exports, "assertAllowed", { enumerable: true, get: function () { return action_js_1.assertAllowed; } });
 Object.defineProperty(exports, "assertAuthorityLive", { enumerable: true, get: function () { return action_js_1.assertAuthorityLive; } });
 Object.defineProperty(exports, "withExecutionLease", { enumerable: true, get: function () { return action_js_1.withExecutionLease; } });
+var capability_js_1 = require("./capability.js");
+Object.defineProperty(exports, "CAPABILITY_FORMAT", { enumerable: true, get: function () { return capability_js_1.CAPABILITY_FORMAT; } });
+Object.defineProperty(exports, "DEFAULT_OPENAPI_OPERATION_MAP", { enumerable: true, get: function () { return capability_js_1.DEFAULT_OPENAPI_OPERATION_MAP; } });
+Object.defineProperty(exports, "INTEROP_CONTRACT_VERSION", { enumerable: true, get: function () { return capability_js_1.INTEROP_CONTRACT_VERSION; } });
+Object.defineProperty(exports, "OPENAPI_ADAPTER_ID", { enumerable: true, get: function () { return capability_js_1.OPENAPI_ADAPTER_ID; } });
+Object.defineProperty(exports, "discoveryGrantsAuthority", { enumerable: true, get: function () { return capability_js_1.discoveryGrantsAuthority; } });
+Object.defineProperty(exports, "ingestOpenApiDocument", { enumerable: true, get: function () { return capability_js_1.ingestOpenApiDocument; } });

package/dist/cjs/types.js

@@ -2,6 +2,6 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BASE_URL = exports.AUCTRA_SDK_VERSION = void 0;
-exports.AUCTRA_SDK_VERSION = "0.7.18";
+exports.AUCTRA_SDK_VERSION = "0.7.19";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 exports.DEFAULT_BASE_URL = "https://app.auctra.tech";

package/dist/esm/capability.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Vendor-neutral OpenAPI ingest for integrator apps.
+ * Catalog membership is not a grant. Mapping is an explicit table only.
+ * Keep behavior aligned with @auctra/authority-protocol capability.openapi.
+ */
+export declare const OPENAPI_ADAPTER_ID = "auctra.openapi-catalog.v0.1";
+export declare const CAPABILITY_FORMAT = "auctra-capability.v0.1";
+export declare const INTEROP_CONTRACT_VERSION = "0.1";
+export declare const DEFAULT_OPENAPI_OPERATION_MAP: Record<string, string>;
+export type CapabilityState = "discovered" | "validated" | "mapped" | "evaluated" | "authorized_request";
+export type IngestIssue = {
+    code: string;
+    message: string;
+};
+export type CapabilityRecord = {
+    format: typeof CAPABILITY_FORMAT;
+    interop_contract_version: typeof INTEROP_CONTRACT_VERSION;
+    state: CapabilityState;
+    source_system: string;
+    source_record_id: string;
+    provider: string;
+    service_id: string;
+    operation_id: string;
+    invocation_type: "http";
+    http_method?: string;
+    path?: string;
+    declared_auth?: string[];
+    retrieved_at: string;
+    auctra_operation_id?: string;
+    mapping_confidence: "unresolved" | "high";
+    untrusted_description?: string;
+};
+export type OpenApiIngestOk = {
+    ok: true;
+    records: CapabilityRecord[];
+    warnings: IngestIssue[];
+};
+export type OpenApiIngestFail = {
+    ok: false;
+    issues: IngestIssue[];
+};
+/** Catalog rows never grant Auctra authority. */
+export declare function discoveryGrantsAuthority(_record?: CapabilityRecord): false;
+/**
+ * Ingest an OpenAPI 3 document as untrusted capability metadata.
+ * Does not call Auctra Cloud. Does not grant authority.
+ */
+export declare function ingestOpenApiDocument(doc: Record<string, unknown>, opts?: {
+    source_system?: string;
+    provider?: string;
+    service_id?: string;
+    at?: Date;
+    operationMap?: Record<string, string>;
+}): OpenApiIngestOk | OpenApiIngestFail;
+//# sourceMappingURL=capability.d.ts.map

package/dist/esm/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/capability.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAC1D,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGhE,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,WAAW,GACX,oBAAoB,CAAC;AAEzB,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,KAAK,EAAE,eAAe,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,YAAY,GAAG,MAAM,CAAC;IAC1C,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC;AAErE,iDAAiD;AACjD,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAE1E;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,GAAE;IACJ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,GACL,eAAe,GAAG,iBAAiB,CAkErC"}

package/dist/esm/capability.js

@@ -0,0 +1,85 @@
+/**
+ * Vendor-neutral OpenAPI ingest for integrator apps.
+ * Catalog membership is not a grant. Mapping is an explicit table only.
+ * Keep behavior aligned with @auctra/authority-protocol capability.openapi.
+ */
+export const OPENAPI_ADAPTER_ID = "auctra.openapi-catalog.v0.1";
+export const CAPABILITY_FORMAT = "auctra-capability.v0.1";
+export const INTEROP_CONTRACT_VERSION = "0.1";
+export const DEFAULT_OPENAPI_OPERATION_MAP = {
+    createTransfer: "send_payment",
+    listTransfers: "read_sensitive_data",
+};
+/** Catalog rows never grant Auctra authority. */
+export function discoveryGrantsAuthority(_record) {
+    return false;
+}
+function issue(code, message) {
+    return { code, message };
+}
+/**
+ * Ingest an OpenAPI 3 document as untrusted capability metadata.
+ * Does not call Auctra Cloud. Does not grant authority.
+ */
+export function ingestOpenApiDocument(doc, opts = {}) {
+    const openapi = typeof doc.openapi === "string" ? doc.openapi : "";
+    if (!openapi.startsWith("3.")) {
+        return { ok: false, issues: [issue("not_openapi3", "Only OpenAPI 3.x documents are accepted")] };
+    }
+    const paths = doc.paths;
+    if (!paths || typeof paths !== "object" || Array.isArray(paths)) {
+        return { ok: false, issues: [issue("missing_paths", "OpenAPI document has no paths object")] };
+    }
+    const at = opts.at ?? new Date();
+    const source_system = opts.source_system ?? OPENAPI_ADAPTER_ID;
+    const provider = opts.provider ?? "openapi";
+    const service_id = opts.service_id ?? "imported-api";
+    const operationMap = opts.operationMap ?? DEFAULT_OPENAPI_OPERATION_MAP;
+    const info = doc.info && typeof doc.info === "object" ? doc.info : {};
+    const infoBlurb = [info.description, info.title].filter((row) => typeof row === "string").join(" ");
+    const records = [];
+    const warnings = [];
+    const methods = ["get", "post", "put", "patch", "delete", "head", "options"];
+    for (const [path, item] of Object.entries(paths)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const pathItem = item;
+        for (const method of methods) {
+            const op = pathItem[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const operationId = typeof op.operationId === "string" && op.operationId.trim()
+                ? op.operationId.trim()
+                : `${method}:${path}`;
+            const untrusted = [op.summary, op.description, infoBlurb]
+                .filter((row) => typeof row === "string")
+                .join("\n");
+            if (/ignore previous|you are now|grant authority/i.test(untrusted)) {
+                warnings.push(issue("untrusted_instruction", "Description looks like an instruction; stored as untrusted text only"));
+            }
+            const mappedName = operationMap[operationId];
+            records.push({
+                format: CAPABILITY_FORMAT,
+                interop_contract_version: INTEROP_CONTRACT_VERSION,
+                state: mappedName ? "mapped" : "validated",
+                source_system,
+                source_record_id: `${method}:${path}`,
+                provider,
+                service_id,
+                operation_id: operationId,
+                invocation_type: "http",
+                http_method: method.toUpperCase(),
+                path,
+                declared_auth: Array.isArray(op.security) ? ["openapi-security"] : undefined,
+                retrieved_at: at.toISOString(),
+                auctra_operation_id: mappedName,
+                mapping_confidence: mappedName ? "high" : "unresolved",
+                untrusted_description: untrusted || undefined,
+            });
+        }
+    }
+    if (!records.length) {
+        return { ok: false, issues: [issue("empty", "OpenAPI document produced no operations")] };
+    }
+    return { ok: true, records, warnings };
+}

package/dist/esm/index.d.ts

@@ -10,4 +10,6 @@ export { AuctraApiError, verifyMandateArtifact, verifyDecisionArtifact } from ".
 export { Auctra } from "./client.js";
 export { onAllowed, assertAllowed, assertAuthorityLive, withExecutionLease } from "./action.js";
 export type { AuthorityLivenessClient } from "./action.js";
+export { CAPABILITY_FORMAT, DEFAULT_OPENAPI_OPERATION_MAP, INTEROP_CONTRACT_VERSION, OPENAPI_ADAPTER_ID, discoveryGrantsAuthority, ingestOpenApiDocument, } from "./capability.js";
+export type { CapabilityRecord, CapabilityState, IngestIssue, OpenApiIngestFail, OpenApiIngestOk, } from "./capability.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClE,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClE,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,wBAAwB,EACxB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/esm/index.js

@@ -8,3 +8,4 @@ export { AUCTRA_SDK_VERSION, DEFAULT_BASE_URL } from "./types.js";
 export { AuctraApiError, verifyMandateArtifact, verifyDecisionArtifact } from "./artifacts.js";
 export { Auctra } from "./client.js";
 export { onAllowed, assertAllowed, assertAuthorityLive, withExecutionLease } from "./action.js";
+export { CAPABILITY_FORMAT, DEFAULT_OPENAPI_OPERATION_MAP, INTEROP_CONTRACT_VERSION, OPENAPI_ADAPTER_ID, discoveryGrantsAuthority, ingestOpenApiDocument, } from "./capability.js";

package/dist/esm/types.d.ts

@@ -1,5 +1,5 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
-export declare const AUCTRA_SDK_VERSION = "0.7.18";
+export declare const AUCTRA_SDK_VERSION = "0.7.19";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export declare const DEFAULT_BASE_URL = "https://app.auctra.tech";
 export type AgentEnvironment = "dev" | "staging" | "production";

package/dist/esm/types.js

@@ -1,4 +1,4 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
-export const AUCTRA_SDK_VERSION = "0.7.18";
+export const AUCTRA_SDK_VERSION = "0.7.19";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export const DEFAULT_BASE_URL = "https://app.auctra.tech";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auctra/sdk",
-  "version": "0.7.18",
+  "version": "0.7.19",
   "description": "Authority Protocol SDK — issue portable authority, evaluate/execute actions, verify evidence",
   "homepage": "https://www.auctra.tech/docs",
   "bugs": {

package/src/capability.ts

@@ -0,0 +1,140 @@
+/**
+ * Vendor-neutral OpenAPI ingest for integrator apps.
+ * Catalog membership is not a grant. Mapping is an explicit table only.
+ * Keep behavior aligned with @auctra/authority-protocol capability.openapi.
+ */
+
+export const OPENAPI_ADAPTER_ID = "auctra.openapi-catalog.v0.1";
+export const CAPABILITY_FORMAT = "auctra-capability.v0.1";
+export const INTEROP_CONTRACT_VERSION = "0.1";
+
+export const DEFAULT_OPENAPI_OPERATION_MAP: Record<string, string> = {
+  createTransfer: "send_payment",
+  listTransfers: "read_sensitive_data",
+};
+
+export type CapabilityState =
+  | "discovered"
+  | "validated"
+  | "mapped"
+  | "evaluated"
+  | "authorized_request";
+
+export type IngestIssue = { code: string; message: string };
+
+export type CapabilityRecord = {
+  format: typeof CAPABILITY_FORMAT;
+  interop_contract_version: typeof INTEROP_CONTRACT_VERSION;
+  state: CapabilityState;
+  source_system: string;
+  source_record_id: string;
+  provider: string;
+  service_id: string;
+  operation_id: string;
+  invocation_type: "http";
+  http_method?: string;
+  path?: string;
+  declared_auth?: string[];
+  retrieved_at: string;
+  auctra_operation_id?: string;
+  mapping_confidence: "unresolved" | "high";
+  untrusted_description?: string;
+};
+
+export type OpenApiIngestOk = {
+  ok: true;
+  records: CapabilityRecord[];
+  warnings: IngestIssue[];
+};
+
+export type OpenApiIngestFail = { ok: false; issues: IngestIssue[] };
+
+/** Catalog rows never grant Auctra authority. */
+export function discoveryGrantsAuthority(_record?: CapabilityRecord): false {
+  return false;
+}
+
+function issue(code: string, message: string): IngestIssue {
+  return { code, message };
+}
+
+/**
+ * Ingest an OpenAPI 3 document as untrusted capability metadata.
+ * Does not call Auctra Cloud. Does not grant authority.
+ */
+export function ingestOpenApiDocument(
+  doc: Record<string, unknown>,
+  opts: {
+    source_system?: string;
+    provider?: string;
+    service_id?: string;
+    at?: Date;
+    operationMap?: Record<string, string>;
+  } = {},
+): OpenApiIngestOk | OpenApiIngestFail {
+  const openapi = typeof doc.openapi === "string" ? doc.openapi : "";
+  if (!openapi.startsWith("3.")) {
+    return { ok: false, issues: [issue("not_openapi3", "Only OpenAPI 3.x documents are accepted")] };
+  }
+  const paths = doc.paths;
+  if (!paths || typeof paths !== "object" || Array.isArray(paths)) {
+    return { ok: false, issues: [issue("missing_paths", "OpenAPI document has no paths object")] };
+  }
+
+  const at = opts.at ?? new Date();
+  const source_system = opts.source_system ?? OPENAPI_ADAPTER_ID;
+  const provider = opts.provider ?? "openapi";
+  const service_id = opts.service_id ?? "imported-api";
+  const operationMap = opts.operationMap ?? DEFAULT_OPENAPI_OPERATION_MAP;
+  const info = doc.info && typeof doc.info === "object" ? (doc.info as Record<string, unknown>) : {};
+  const infoBlurb = [info.description, info.title].filter((row) => typeof row === "string").join(" ");
+
+  const records: CapabilityRecord[] = [];
+  const warnings: IngestIssue[] = [];
+  const methods = ["get", "post", "put", "patch", "delete", "head", "options"] as const;
+
+  for (const [path, item] of Object.entries(paths as Record<string, unknown>)) {
+    if (!item || typeof item !== "object") continue;
+    const pathItem = item as Record<string, Record<string, unknown>>;
+    for (const method of methods) {
+      const op = pathItem[method];
+      if (!op || typeof op !== "object") continue;
+      const operationId =
+        typeof op.operationId === "string" && op.operationId.trim()
+          ? op.operationId.trim()
+          : `${method}:${path}`;
+      const untrusted = [op.summary, op.description, infoBlurb]
+        .filter((row) => typeof row === "string")
+        .join("\n");
+      if (/ignore previous|you are now|grant authority/i.test(untrusted)) {
+        warnings.push(
+          issue("untrusted_instruction", "Description looks like an instruction; stored as untrusted text only"),
+        );
+      }
+      const mappedName = operationMap[operationId];
+      records.push({
+        format: CAPABILITY_FORMAT,
+        interop_contract_version: INTEROP_CONTRACT_VERSION,
+        state: mappedName ? "mapped" : "validated",
+        source_system,
+        source_record_id: `${method}:${path}`,
+        provider,
+        service_id,
+        operation_id: operationId,
+        invocation_type: "http",
+        http_method: method.toUpperCase(),
+        path,
+        declared_auth: Array.isArray(op.security) ? ["openapi-security"] : undefined,
+        retrieved_at: at.toISOString(),
+        auctra_operation_id: mappedName,
+        mapping_confidence: mappedName ? "high" : "unresolved",
+        untrusted_description: untrusted || undefined,
+      });
+    }
+  }
+
+  if (!records.length) {
+    return { ok: false, issues: [issue("empty", "OpenAPI document produced no operations")] };
+  }
+  return { ok: true, records, warnings };
+}

package/src/index.ts

@@ -10,3 +10,18 @@ export { AuctraApiError, verifyMandateArtifact, verifyDecisionArtifact } from ".
 export { Auctra } from "./client.js";
 export { onAllowed, assertAllowed, assertAuthorityLive, withExecutionLease } from "./action.js";
 export type { AuthorityLivenessClient } from "./action.js";
+export {
+  CAPABILITY_FORMAT,
+  DEFAULT_OPENAPI_OPERATION_MAP,
+  INTEROP_CONTRACT_VERSION,
+  OPENAPI_ADAPTER_ID,
+  discoveryGrantsAuthority,
+  ingestOpenApiDocument,
+} from "./capability.js";
+export type {
+  CapabilityRecord,
+  CapabilityState,
+  IngestIssue,
+  OpenApiIngestFail,
+  OpenApiIngestOk,
+} from "./capability.js";

package/src/types.ts

@@ -1,6 +1,6 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
 
-export const AUCTRA_SDK_VERSION = "0.7.18";
+export const AUCTRA_SDK_VERSION = "0.7.19";
 
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export const DEFAULT_BASE_URL = "https://app.auctra.tech";