@xemahq/kernel-contracts 0.22.2 → 0.22.3

package/dist/agent-workspace/awp-spec.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://xema.dev/schemas/awp-spec.v1.json",
-  "emittedAt": "2026-07-01T10:48:07.595Z",
+  "emittedAt": "2026-07-02T07:22:41.877Z",
   "spec": {
     "id": "awp/v1",
     "version": "1.2.0",

package/dist/connector/index.d.ts

@@ -2,6 +2,8 @@ export * from './lib/adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';
+export * from './lib/provider-descriptor';
+export * from './lib/connector-descriptor';
 export * from './lib/envelope-schema';
 export * from './lib/filter-expr';
 export * from './lib/filter-expr-schema';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC"}

package/dist/connector/index.js

@@ -18,6 +18,8 @@ __exportStar(require("./lib/adapter-kind"), exports);
 __exportStar(require("./lib/capability"), exports);
 __exportStar(require("./lib/credential-kind"), exports);
 __exportStar(require("./lib/onboarding-manifest"), exports);
+__exportStar(require("./lib/provider-descriptor"), exports);
+__exportStar(require("./lib/connector-descriptor"), exports);
 __exportStar(require("./lib/envelope-schema"), exports);
 __exportStar(require("./lib/filter-expr"), exports);
 __exportStar(require("./lib/filter-expr-schema"), exports);

package/dist/connector/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,mDAAiC;AACjC,wDAAsC;AACtC,4DAA0C;AAC1C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,mDAAiC;AACjC,wDAAsC;AACtC,4DAA0C;AAC1C,4DAA0C;AAC1C,6DAA2C;AAC3C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C"}

package/dist/connector/lib/connector-descriptor.d.ts

@@ -0,0 +1,13 @@
+import type { AdapterKindRef } from './adapter-kind';
+import type { CredentialKind } from './credential-kind';
+export interface ConnectorDescriptor {
+    readonly connectorKey: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly iconName: string;
+    readonly providerKey: string;
+    readonly scopes: readonly string[];
+    readonly connectionCredentialKind: CredentialKind;
+    readonly adapterKind: AdapterKindRef;
+}
+//# sourceMappingURL=connector-descriptor.d.ts.map

package/dist/connector/lib/connector-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AASxD,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAU7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAOnC,QAAQ,CAAC,wBAAwB,EAAE,cAAc,CAAC;IAOlD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACtC"}

package/dist/connector/lib/connector-descriptor.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=connector-descriptor.js.map

package/dist/connector/lib/connector-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":""}

package/dist/connector/lib/provider-descriptor.d.ts

@@ -0,0 +1,37 @@
+import type { CredentialFieldSpec } from './onboarding-manifest';
+export declare enum ProviderAppAuthKind {
+    OAuth2 = "oauth2",
+    AppInstall = "app_install",
+    None = "none"
+}
+export declare enum ProviderOrigin {
+    Kernel = "kernel",
+    Platform = "platform",
+    Biome = "biome"
+}
+export declare enum ProviderCredentialScope {
+    Platform = "platform",
+    Org = "org"
+}
+export declare const PROVIDER_CREDENTIAL_SCOPE_ORDER: readonly ProviderCredentialScope[];
+export interface ProviderOAuthEndpoints {
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
+    readonly clientIdEnvVar?: string;
+    readonly clientSecretEnvVar?: string;
+}
+export interface ProviderDescriptor {
+    readonly providerKey: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly iconName: string;
+    readonly category: string;
+    readonly appAuthKind: ProviderAppAuthKind;
+    readonly origin: ProviderOrigin;
+    readonly appCredentialSchema?: readonly CredentialFieldSpec[];
+    readonly oauthEndpoints?: ProviderOAuthEndpoints;
+    readonly allowOrgOverride: boolean;
+}
+export declare function providerRequiresAppCredential(provider: Pick<ProviderDescriptor, 'appAuthKind'>): boolean;
+//# sourceMappingURL=provider-descriptor.d.ts.map

package/dist/connector/lib/provider-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/provider-descriptor.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAQjE,oBAAY,mBAAmB;IAO7B,MAAM,WAAW;IAMjB,UAAU,gBAAgB;IAO1B,IAAI,SAAS;CACd;AAaD,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,KAAK,UAAU;CAChB;AAiBD,oBAAY,uBAAuB;IACjC,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAGD,eAAO,MAAM,+BAA+B,EAAE,SAAS,uBAAuB,EACb,CAAC;AAOlE,MAAM,WAAW,sBAAsB;IAErC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAQ1B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAQjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAOD,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAE1C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAQhC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAM9D,QAAQ,CAAC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IAOjD,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAOD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,GAChD,OAAO,CAET"}

package/dist/connector/lib/provider-descriptor.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_CREDENTIAL_SCOPE_ORDER = exports.ProviderCredentialScope = exports.ProviderOrigin = exports.ProviderAppAuthKind = void 0;
+exports.providerRequiresAppCredential = providerRequiresAppCredential;
+var ProviderAppAuthKind;
+(function (ProviderAppAuthKind) {
+    ProviderAppAuthKind["OAuth2"] = "oauth2";
+    ProviderAppAuthKind["AppInstall"] = "app_install";
+    ProviderAppAuthKind["None"] = "none";
+})(ProviderAppAuthKind || (exports.ProviderAppAuthKind = ProviderAppAuthKind = {}));
+var ProviderOrigin;
+(function (ProviderOrigin) {
+    ProviderOrigin["Kernel"] = "kernel";
+    ProviderOrigin["Platform"] = "platform";
+    ProviderOrigin["Biome"] = "biome";
+})(ProviderOrigin || (exports.ProviderOrigin = ProviderOrigin = {}));
+var ProviderCredentialScope;
+(function (ProviderCredentialScope) {
+    ProviderCredentialScope["Platform"] = "platform";
+    ProviderCredentialScope["Org"] = "org";
+})(ProviderCredentialScope || (exports.ProviderCredentialScope = ProviderCredentialScope = {}));
+exports.PROVIDER_CREDENTIAL_SCOPE_ORDER = [ProviderCredentialScope.Org, ProviderCredentialScope.Platform];
+function providerRequiresAppCredential(provider) {
+    return provider.appAuthKind !== ProviderAppAuthKind.None;
+}
+//# sourceMappingURL=provider-descriptor.js.map

package/dist/connector/lib/provider-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/provider-descriptor.ts"],"names":[],"mappings":";;;AAgLA,sEAIC;AAlJD,IAAY,mBAqBX;AArBD,WAAY,mBAAmB;IAO7B,wCAAiB,CAAA;IAMjB,iDAA0B,CAAA;IAO1B,oCAAa,CAAA;AACf,CAAC,EArBW,mBAAmB,mCAAnB,mBAAmB,QAqB9B;AAaD,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,uCAAqB,CAAA;IACrB,iCAAe,CAAA;AACjB,CAAC,EAJW,cAAc,8BAAd,cAAc,QAIzB;AAiBD,IAAY,uBAGX;AAHD,WAAY,uBAAuB;IACjC,gDAAqB,CAAA;IACrB,sCAAW,CAAA;AACb,CAAC,EAHW,uBAAuB,uCAAvB,uBAAuB,QAGlC;AAGY,QAAA,+BAA+B,GAC1C,CAAC,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;AAgFlE,SAAgB,6BAA6B,CAC3C,QAAiD;IAEjD,OAAO,QAAQ,CAAC,WAAW,KAAK,mBAAmB,CAAC,IAAI,CAAC;AAC3D,CAAC"}

package/dist/policy/lib/policy.d.ts

@@ -12,7 +12,8 @@ export declare enum CredentialPrecedenceSource {
     Explicit = "explicit",
     CapabilityDefault = "capability_default",
     ProjectDefault = "project_default",
-    OrgDefault = "org_default"
+    OrgDefault = "org_default",
+    PlatformDefault = "platform_default"
 }
 export declare const CredentialPrecedenceSourceSchema: z.ZodEnum<typeof CredentialPrecedenceSource>;
 export type PolicyRequest = ExecutionContext;

package/dist/policy/lib/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAShE,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,aAAa,mBAAmB;CACjC;AAED,eAAO,MAAM,wBAAwB,sCAAmC,CAAC;AAczE,oBAAY,0BAA0B;IACpC,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,cAAc,oBAAoB;IAClC,UAAU,gBAAgB;CAC3B;AAED,eAAO,MAAM,gCAAgC,8CAE5C,CAAC;AAWF,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CACjC,CAAC;AAWzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,CAAC;IAWvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAM7B,2BAA2B,CAAC,EAAE,0BAA0B,CAAC;CAC1D;AAED,eAAO,MAAM,oBAAoB,EAO3B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAShE,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,aAAa,mBAAmB;CACjC;AAED,eAAO,MAAM,wBAAwB,sCAAmC,CAAC;AAgBzE,oBAAY,0BAA0B;IACpC,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,cAAc,oBAAoB;IAClC,UAAU,gBAAgB;IAO1B,eAAe,qBAAqB;CACrC;AAED,eAAO,MAAM,gCAAgC,8CAE5C,CAAC;AAWF,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CACjC,CAAC;AAWzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,SAAS,CAAC;IAWvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAM7B,2BAA2B,CAAC,EAAE,0BAA0B,CAAC;CAC1D;AAED,eAAO,MAAM,oBAAoB,EAO3B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/policy/lib/policy.js

@@ -18,6 +18,7 @@ var CredentialPrecedenceSource;
     CredentialPrecedenceSource["CapabilityDefault"] = "capability_default";
     CredentialPrecedenceSource["ProjectDefault"] = "project_default";
     CredentialPrecedenceSource["OrgDefault"] = "org_default";
+    CredentialPrecedenceSource["PlatformDefault"] = "platform_default";
 })(CredentialPrecedenceSource || (exports.CredentialPrecedenceSource = CredentialPrecedenceSource = {}));
 exports.CredentialPrecedenceSourceSchema = zod_1.z.nativeEnum(CredentialPrecedenceSource);
 exports.PolicyRequestSchema = execution_context_1.ExecutionContextSchema;

package/dist/policy/lib/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,+DAGiC;AACjC,+CAGuB;AACvB,+CAAgE;AAShE,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,mCAAa,CAAA;IACb,sDAAgC,CAAA;AAClC,CAAC,EAJW,kBAAkB,kCAAlB,kBAAkB,QAI7B;AAEY,QAAA,wBAAwB,GAAG,OAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAczE,IAAY,0BAKX;AALD,WAAY,0BAA0B;IACpC,mDAAqB,CAAA;IACrB,sEAAwC,CAAA;IACxC,gEAAkC,CAAA;IAClC,wDAA0B,CAAA;AAC5B,CAAC,EALW,0BAA0B,0CAA1B,0BAA0B,QAKrC;AAEY,QAAA,gCAAgC,GAAG,OAAC,CAAC,UAAU,CAC1D,0BAA0B,CAC3B,CAAC;AAaW,QAAA,mBAAmB,GAC9B,0CAAsB,CAAC;AAmCZ,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,gCAAwB;IAC9B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,oCAAsB,CAAC,CAAC,QAAQ,EAAE;IACvD,UAAU,EAAE,6BAAe,CAAC,QAAQ,EAAE;IACtC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,2BAA2B,EAAE,wCAAgC,CAAC,QAAQ,EAAE;CACzE,CAA8B,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/policy/lib/policy.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,+DAGiC;AACjC,+CAGuB;AACvB,+CAAgE;AAShE,IAAY,kBAIX;AAJD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,mCAAa,CAAA;IACb,sDAAgC,CAAA;AAClC,CAAC,EAJW,kBAAkB,kCAAlB,kBAAkB,QAI7B;AAEY,QAAA,wBAAwB,GAAG,OAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAgBzE,IAAY,0BAYX;AAZD,WAAY,0BAA0B;IACpC,mDAAqB,CAAA;IACrB,sEAAwC,CAAA;IACxC,gEAAkC,CAAA;IAClC,wDAA0B,CAAA;IAO1B,kEAAoC,CAAA;AACtC,CAAC,EAZW,0BAA0B,0CAA1B,0BAA0B,QAYrC;AAEY,QAAA,gCAAgC,GAAG,OAAC,CAAC,UAAU,CAC1D,0BAA0B,CAC3B,CAAC;AAaW,QAAA,mBAAmB,GAC9B,0CAAsB,CAAC;AAmCZ,QAAA,oBAAoB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,gCAAwB;IAC9B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,oCAAsB,CAAC,CAAC,QAAQ,EAAE;IACvD,UAAU,EAAE,6BAAe,CAAC,QAAQ,EAAE;IACtC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,2BAA2B,EAAE,wCAAgC,CAAC,QAAQ,EAAE;CACzE,CAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.22.2",
+  "version": "0.22.3",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/connector/index.ts

@@ -2,6 +2,8 @@ export * from './lib/adapter-kind';
 export * from './lib/capability';
 export * from './lib/credential-kind';
 export * from './lib/onboarding-manifest';
+export * from './lib/provider-descriptor';
+export * from './lib/connector-descriptor';
 export * from './lib/envelope-schema';
 export * from './lib/filter-expr';
 export * from './lib/filter-expr-schema';

package/src/connector/lib/connector-descriptor.ts

@@ -0,0 +1,66 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Connector descriptor — a capability surface authenticated by ONE provider
+ *
+ * A **Connector** is what a user actually connects: Gmail, Google Drive,
+ * generic IMAP, generic SMTP, a GitHub SCM connector. Every connector names
+ * the **Provider** it authenticates against (`providerKey`) and the incremental
+ * OAuth `scopes` it needs from that provider. The catalog groups connectors by
+ * provider so ONE app credential (per `ProviderDescriptor`) backs many
+ * connectors.
+ *
+ * This descriptor is the connector-registry face of an `IntegrationProvider
+ * Module`: the module carries the executable webhook/action/resource handlers;
+ * this descriptor carries the *catalog + connect* metadata the framework needs
+ * to render the provider-grouped catalog, drive consent with the right scopes,
+ * and resolve the right per-connection credential kind.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { AdapterKindRef } from './adapter-kind';
+import type { CredentialKind } from './credential-kind';
+
+/**
+ * A connector in the catalog. `connectorKey` aligns with the persisted
+ * `ConnectorKind` wire value (e.g. `GMAIL`, `IMAP_GENERIC`, `SMTP_GENERIC`)
+ * but is typed as a string here to keep the kernel `connector` contract
+ * package free of the persisted `ConnectorKind` enum (which lives in
+ * platform-common's integration-webhooks); the connector-gateway maps the two.
+ */
+export interface ConnectorDescriptor {
+  /** Stable connector key — aligns with the persisted `ConnectorKind`. */
+  readonly connectorKey: string;
+  /** Human-readable name — `Gmail`, `Generic IMAP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the connector row. */
+  readonly description: string;
+  /** Lucide-react icon name; may differ from the provider's icon. */
+  readonly iconName: string;
+
+  /** The provider (authenticating authority) this connector belongs to. */
+  readonly providerKey: string;
+
+  /**
+   * Incremental OAuth scopes this connector requests from its provider. Empty
+   * for connectors whose provider `appAuthKind` is `None` (IMAP/SMTP). When a
+   * second connector of the same OAuth provider is connected, the consent
+   * driver requests the UNION of already-granted + these scopes (incremental
+   * consent) so one app credential accrues capability without re-consent for
+   * scopes already held.
+   */
+  readonly scopes: readonly string[];
+
+  /**
+   * How an individual connection to THIS connector authenticates at runtime
+   * (the per-connection wallet/token). `oauth_user` for OAuth connectors,
+   * `imap_auth` / `smtp_auth` for the mail wallets, `pat` / `api_key`, …
+   */
+  readonly connectionCredentialKind: CredentialKind;
+
+  /**
+   * The adapter category this connector plugs into (`mail`, `scm`, …). Drives
+   * where normalized inbound envelopes are forwarded and which project-binding
+   * surface the connector appears under.
+   */
+  readonly adapterKind: AdapterKindRef;
+}

package/src/connector/lib/provider-descriptor.ts

@@ -0,0 +1,181 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Provider descriptor — the authenticating authority ("app") behind N connectors
+ *
+ * A **Provider** is the identity/authority a set of connectors authenticates
+ * against — e.g. `google`, `microsoft`, `github`, `slack`, `smtp`, `imap`.
+ * ONE provider owns ONE **app credential** (a Google Cloud OAuth client, a
+ * GitHub App private key, …) and fans out to MANY **connectors** (Gmail,
+ * Google Drive, Google Calendar …), each of which reuses that single app
+ * credential with its own incremental scopes.
+ *
+ * This is the "Google is a world" fix: the catalog lists connectors grouped
+ * under one provider card; the app credential is provided once (by a platform
+ * admin, or overridden per-org as BYO) and every connector under the provider
+ * reuses it. Adding a new Google service later is a new *connector* with new
+ * scopes — never a new credential and never a framework change.
+ *
+ * The descriptor is a **runtime contract** describing how a provider's app
+ * credential is obtained and where it lives. Actual secret VALUES are never
+ * carried here — only the SCHEMA of what an admin must supply
+ * (`appCredentialSchema`) and non-secret OAuth endpoint metadata. Secrets are
+ * held by the credential broker + custody, referenced by env-var name or
+ * custody ref, never inlined.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import type { CredentialFieldSpec } from './onboarding-manifest';
+
+/**
+ * How a provider's APP-level credential authenticates. This is distinct from
+ * a *connector's* per-connection `CredentialKind` (how an individual user/
+ * mailbox connection authenticates) — it describes the shared "app" that the
+ * platform/org registers once.
+ */
+export enum ProviderAppAuthKind {
+  /**
+   * 3-legged OAuth: the app is a registered OAuth client (clientId/secret).
+   * Connecting a connector runs an authorization-code consent redirect using
+   * the app credential + the connector's scopes. e.g. Google, Microsoft,
+   * Slack.
+   */
+  OAuth2 = 'oauth2',
+  /**
+   * App-installation flow (GitHub App / GitLab App / Atlassian Connect): the
+   * app authenticates via an app id + private key and the user installs it
+   * onto their account/org. e.g. GitHub.
+   */
+  AppInstall = 'app_install',
+  /**
+   * No shared app credential at all — every connection carries its own
+   * complete secret (a mailbox host+user+password, a raw API key). The
+   * connector is connectable with NO platform/org setup. e.g. generic SMTP,
+   * generic IMAP.
+   */
+  None = 'none',
+}
+
+/**
+ * Who shipped a provider. Determines WHICH admin fulfils its app-credential
+ * requirement and at which scope the requirement is registered.
+ *
+ *  - `kernel`   — a first-party provider baked into the platform.
+ *  - `platform` — shipped by a platform (Layer-2) service/biome installed
+ *                 platform-wide; platform admin fulfils it.
+ *  - `biome`    — introduced by a biome. When that biome is installed at ORG
+ *                 scope, the requirement is org-scoped (the org admin BYO-fills
+ *                 it) because the platform never shipped the provider.
+ */
+export enum ProviderOrigin {
+  Kernel = 'kernel',
+  Platform = 'platform',
+  Biome = 'biome',
+}
+
+/**
+ * The two scopes at which a provider's APP credential can be provisioned.
+ * Deliberately a SEPARATE, minimal enum from the 5-tier ownership
+ * `ScopeSource` and from the credential-broker's per-connection
+ * `CredentialScopeTier` — app-credential provisioning is a strict 2-tier
+ * concern: a platform-wide default that an org may override.
+ *
+ * Resolution precedence (narrowest wins):
+ *
+ *   Org (BYO)  >  Platform (default)  >  [legacy env-var fallback]  >  unset
+ *
+ * An unset REQUIRED app credential is surfaced to the correct admin and the
+ * connector reports "needs setup" — it never silently falls through to an
+ * unauthenticated request.
+ */
+export enum ProviderCredentialScope {
+  Platform = 'platform',
+  Org = 'org',
+}
+
+/** Precedence order for app-credential resolution — index 0 wins. */
+export const PROVIDER_CREDENTIAL_SCOPE_ORDER: readonly ProviderCredentialScope[] =
+  [ProviderCredentialScope.Org, ProviderCredentialScope.Platform];
+
+/**
+ * Non-secret OAuth endpoint metadata for a `ProviderAppAuthKind.OAuth2`
+ * provider. Client id/secret are NOT here — they are the app credential,
+ * resolved from a provision (or the legacy env fallback) at consent time.
+ */
+export interface ProviderOAuthEndpoints {
+  /** Authorization-code consent endpoint (where the user is redirected). */
+  readonly authorizationUrl: string;
+  /** Token-exchange endpoint (code→token, refresh-token rotation). */
+  readonly tokenUrl: string;
+  /**
+   * Extra authorize-request params a provider needs to actually mint a
+   * refresh token / do incremental consent. Non-secret. e.g. Google needs
+   * `{ access_type: 'offline', include_granted_scopes: 'true', prompt:
+   * 'consent' }`. Kept explicit rather than hardcoded in the driver so a new
+   * OAuth provider is pure data.
+   */
+  readonly extraAuthorizeParams?: Readonly<Record<string, string>>;
+  /**
+   * Legacy env-var NAMES the OAuth driver falls back to for the app
+   * client id / secret when no provision exists yet (bootstrap before the
+   * platform-admin UI is used). Never the secret itself. Optional — a
+   * provider with no env fallback simply reports "needs setup" until an
+   * admin provisions it.
+   */
+  readonly clientIdEnvVar?: string;
+  readonly clientSecretEnvVar?: string;
+}
+
+/**
+ * A first-class Provider (authenticating authority). Registered in the
+ * provider registry alongside — but distinct from — the connectors that
+ * reference it via `Connector.providerKey`.
+ */
+export interface ProviderDescriptor {
+  /** Stable lowercase slug — `google`, `microsoft`, `github`, `smtp`. */
+  readonly providerKey: string;
+  /** Human-readable name — `Google`, `Microsoft`, `Generic SMTP`. */
+  readonly displayName: string;
+  /** One-sentence description shown on the provider card. */
+  readonly description: string;
+  /** Lucide-react icon name; frontend maps to a component. */
+  readonly iconName: string;
+  /** Catalog grouping label (e.g. `Email`, `Source control`, `Chat`). */
+  readonly category: string;
+
+  /** How the shared app credential authenticates. */
+  readonly appAuthKind: ProviderAppAuthKind;
+  /** Who shipped the provider — drives requirement scope + which admin fills. */
+  readonly origin: ProviderOrigin;
+
+  /**
+   * Schema of the app-credential fields an admin must supply to register the
+   * app (Google → clientId/clientSecret[/pubsubTopic]; GitHub App → appId/
+   * privateKey/webhookSecret). Empty/omitted when `appAuthKind = None`
+   * (nothing to provision — the connector is immediately connectable).
+   */
+  readonly appCredentialSchema?: readonly CredentialFieldSpec[];
+
+  /**
+   * OAuth endpoint metadata — REQUIRED when `appAuthKind = OAuth2`, absent
+   * otherwise.
+   */
+  readonly oauthEndpoints?: ProviderOAuthEndpoints;
+
+  /**
+   * Whether an org may override the platform-default app credential with its
+   * own (BYO app). `false` pins the provider to the platform provision only.
+   * Ignored when `appAuthKind = None` (there is no shared app to override).
+   */
+  readonly allowOrgOverride: boolean;
+}
+
+/**
+ * True when a provider needs an app credential provisioned before any of its
+ * connectors can be connected (i.e. anything other than `None`). Callers use
+ * this to decide whether to surface a "needs setup" state and to whom.
+ */
+export function providerRequiresAppCredential(
+  provider: Pick<ProviderDescriptor, 'appAuthKind'>,
+): boolean {
+  return provider.appAuthKind !== ProviderAppAuthKind.None;
+}

package/src/policy/lib/policy.ts

@@ -33,14 +33,23 @@ export const PolicyDecisionKindSchema = z.nativeEnum(PolicyDecisionKind);
  * Priority, highest wins:
  *   `explicit` (a grant names the binding) > `capability_default`
  *   (the descriptor's `defaultCredentialBindingRef`) > `project_default` >
- *   `org_default`. No match ⇒ the PDP emits NO binding and denies with
- *   `MISSING_CREDENTIAL_BINDING` (never a silent fallback).
+ *   `org_default` > `platform_default` (a deployment-wide default an org may
+ *   override — the Provider–Credential framework's platform tier). No match ⇒
+ *   the PDP emits NO binding and denies with `MISSING_CREDENTIAL_BINDING`
+ *   (never a silent fallback).
  */
 export enum CredentialPrecedenceSource {
   Explicit = 'explicit',
   CapabilityDefault = 'capability_default',
   ProjectDefault = 'project_default',
   OrgDefault = 'org_default',
+  /**
+   * A deployment-wide platform default provision (broadest tier, below org).
+   * An org-scoped default always overrides it. Used by `authorization-api`'s
+   * credential-precedence resolver once this kernel change is published +
+   * consumed (see the Connections framework plan).
+   */
+  PlatformDefault = 'platform_default',
 }
 
 export const CredentialPrecedenceSourceSchema = z.nativeEnum(