@vibesdotdev/connector-base 0.0.1

package/SPEC.md

@@ -0,0 +1,23 @@
+# Connector Base
+
+## Ownership
+
+- **Owns:** Base schemas, interfaces, and resolution utilities for connector packages.
+- **Does not own:** Provider-specific implementations (AWS, Azure, GCP).
+
+## Description
+
+The `connector-base` package defines the runtime `connector/substrate` and `connector/sub-connector` kinds.
+Substrate packages (`connector-aws`, `connector-azure`, etc.) register descriptors against these kinds and provide concrete service clients (S3, SecretsManager, Blob Storage, etc.).
+
+## Public Entrypoints
+
+- `src/index.ts` — types, schemas, and resolution utilities
+- `src/connector.plugin.ts` — runtime plugin for kind registration
+- `src/schemas.ts` — `ConnectorSubstrateDescriptorSchema`, `SubConnectorDescriptorSchema`, `CredentialReferenceSchema`, `AwsCredentialsSchema`
+- `src/resolver.ts` — `resolveCredentialReference`, `resolveAwsCredentials`, `resolveConfigValue`
+
+## Hard Rules
+
+- No provider-specific imports.
+- Must not depend on `@vibesdotdev/secrets` at runtime — accepts `MinimalSecretsStore` shape injected by callers.

package/dist/connector.plugin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Connector Base Plugin
+ *
+ * Registers the connector/substrate and connector/sub-connector runtime kinds.
+ * Individual provider packages (connector-aws, connector-azure, …) register
+ * concrete descriptors against these kinds.
+ */
+export declare const connectorBasePlugin: import("@vibesdotdev/runtime").RuntimePlugin;
+export default connectorBasePlugin;
+//# sourceMappingURL=connector.plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connector.plugin.d.ts","sourceRoot":"","sources":["../src/connector.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,eAAO,MAAM,mBAAmB,8CAoB9B,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/dist/connector.plugin.js

@@ -0,0 +1,26 @@
+/**
+ * Connector Base Plugin
+ *
+ * Registers the connector/substrate and connector/sub-connector runtime kinds.
+ * Individual provider packages (connector-aws, connector-azure, …) register
+ * concrete descriptors against these kinds.
+ */
+import { createRuntimePlugin, createRuntimeKind } from '@vibesdotdev/runtime';
+import { ConnectorSubstrateDescriptorSchema, SubConnectorDescriptorSchema, } from "./schemas.js";
+export const connectorBasePlugin = createRuntimePlugin({
+    id: '@vibesdotdev/connector-base',
+    name: 'Connector Base',
+    description: 'Base connector/substrate and connector/sub-connector kinds for platform integrations.',
+    onRegister: async (runtime) => {
+        runtime.registerKind(createRuntimeKind({
+            id: 'connector/substrate',
+            descriptorSchema: ConnectorSubstrateDescriptorSchema,
+        }));
+        runtime.registerKind(createRuntimeKind({
+            id: 'connector/sub-connector',
+            descriptorSchema: SubConnectorDescriptorSchema,
+        }));
+    },
+});
+export default connectorBasePlugin;
+//# sourceMappingURL=connector.plugin.js.map

package/dist/connector.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.plugin.js","sourceRoot":"","sources":["../src/connector.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EACN,kCAAkC,EAClC,4BAA4B,GAC5B,MAAM,cAAc,CAAC;AAEtB,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;IACtD,EAAE,EAAE,6BAA6B;IACjC,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE,uFAAuF;IAEpG,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC7B,OAAO,CAAC,YAAY,CACnB,iBAAiB,CAAC;YACjB,EAAE,EAAE,qBAAqB;YACzB,gBAAgB,EAAE,kCAAkC;SACpD,CAAC,CACF,CAAC;QAEF,OAAO,CAAC,YAAY,CACnB,iBAAiB,CAAC;YACjB,EAAE,EAAE,yBAAyB;YAC7B,gBAAgB,EAAE,4BAA4B;SAC9C,CAAC,CACF,CAAC;IACH,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Connector Base
+ *
+ * Base contracts, schemas, and interfaces for platform connector packages.
+ * Owned by packages/connector-base.
+ *
+ * Does NOT contain provider-specific implementations.
+ * Use @vibesdotdev/connector-aws for AWS sub-connectors,
+ * @vibesdotdev/connector-azure for Azure, etc.
+ */
+export { ConnectorSubstrateDescriptorSchema, SubConnectorDescriptorSchema, CredentialReferenceSchema, AwsCredentialsSchema, type ConnectorSubstrateDescriptor, type SubConnectorDescriptor, type CredentialReference, type AwsCredentials, } from './schemas.ts';
+export { resolveCredentialReference, resolveAwsCredentials, resolveConfigValue, type ResolutionOptions, } from './resolver.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACN,kCAAkC,EAClC,4BAA4B,EAC5B,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,iBAAiB,GACtB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * Connector Base
+ *
+ * Base contracts, schemas, and interfaces for platform connector packages.
+ * Owned by packages/connector-base.
+ *
+ * Does NOT contain provider-specific implementations.
+ * Use @vibesdotdev/connector-aws for AWS sub-connectors,
+ * @vibesdotdev/connector-azure for Azure, etc.
+ */
+// Descriptor schemas
+export { ConnectorSubstrateDescriptorSchema, SubConnectorDescriptorSchema, CredentialReferenceSchema, AwsCredentialsSchema, } from "./schemas.js";
+// Resolvers (credential resolution, config hydration)
+export { resolveCredentialReference, resolveAwsCredentials, resolveConfigValue, } from "./resolver.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAqB;AACrB,OAAO,EACN,kCAAkC,EAClC,4BAA4B,EAC5B,yBAAyB,EACzB,oBAAoB,GAKpB,MAAM,cAAc,CAAC;AAEtB,sDAAsD;AACtD,OAAO,EACN,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,GAElB,MAAM,eAAe,CAAC"}

package/dist/resolver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Credential and Config Resolution for Connector Base
+ *
+ * Owned by packages/connector-base.
+ * Provides generic reference-resolution utilities used by all
+ * connector-{provider} packages. Avoids hard dependency on
+ * @vibesdotdev/secrets by accepting an injected store shape.
+ */
+import type { CredentialReference, AwsCredentials } from './schemas.ts';
+export interface MinimalSecretsStore {
+    get(scope: string, key: string): Promise<string | undefined>;
+}
+export interface ResolutionOptions {
+    /** Active environment tier — dev / staging / prod */
+    environment: string;
+    /** Optional secrets store for source: 'secret' refs */
+    secretsStore?: MinimalSecretsStore;
+    /** Optional env reader (defaults to process.env) */
+    envReader?: Record<string, string | undefined>;
+}
+export declare class ConnectorResolutionError extends Error {
+    readonly field: string;
+    readonly ref: CredentialReference;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, field: string, ref: CredentialReference, cause?: unknown | undefined);
+}
+/**
+ * Resolve a single credential reference to its string value.
+ */
+export declare function resolveCredentialReference(field: string, ref: CredentialReference, opts: ResolutionOptions): Promise<string>;
+/**
+ * Resolve an AWS credentials block where each field may be a string or
+ * a CredentialReference.
+ */
+export declare function resolveAwsCredentials(creds: AwsCredentials, opts: ResolutionOptions): Promise<{
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}>;
+/**
+ * Resolve an arbitrary config value that may be a bare string or a
+ * CredentialReference.
+ */
+export declare function resolveConfigValue(value: string | CredentialReference, field: string, opts: ResolutionOptions): Promise<string>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMxE,MAAM,WAAW,mBAAmB;IACnC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC/C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAGjD,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,GAAG,EAAE,mBAAmB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAHxB,OAAO,EAAE,MAAM,EACN,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,EACxB,KAAK,CAAC,EAAE,OAAO,YAAA;CAKzB;AAMD;;GAEG;AACH,wBAAsB,0BAA0B,CAC/C,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,EACxB,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,CAkDjB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAC1C,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBlF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,CAGjB"}

package/dist/resolver.js

@@ -0,0 +1,85 @@
+/**
+ * Credential and Config Resolution for Connector Base
+ *
+ * Owned by packages/connector-base.
+ * Provides generic reference-resolution utilities used by all
+ * connector-{provider} packages. Avoids hard dependency on
+ * @vibesdotdev/secrets by accepting an injected store shape.
+ */
+export class ConnectorResolutionError extends Error {
+    field;
+    ref;
+    cause;
+    constructor(message, field, ref, cause) {
+        super(message);
+        this.field = field;
+        this.ref = ref;
+        this.cause = cause;
+        this.name = 'ConnectorResolutionError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Value resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a single credential reference to its string value.
+ */
+export async function resolveCredentialReference(field, ref, opts) {
+    if (ref.source === 'env') {
+        const reader = opts.envReader ?? process.env;
+        const value = reader[ref.key];
+        if (value === undefined || value === '') {
+            throw new ConnectorResolutionError(`Environment variable "${ref.key}" required by field "${field}" is not set.`, field, ref);
+        }
+        return value;
+    }
+    if (ref.source === 'secret') {
+        if (!opts.secretsStore) {
+            throw new ConnectorResolutionError(`Secrets store unavailable — cannot resolve { source: 'secret', key: '${ref.key}' } for field "${field}".`, field, ref);
+        }
+        const scope = ref.scope ?? opts.environment;
+        let value;
+        try {
+            value = await opts.secretsStore.get(scope, ref.key);
+        }
+        catch (err) {
+            throw new ConnectorResolutionError(`Secrets store lookup failed for "${field}" (key "${ref.key}", scope "${scope}"): ${err instanceof Error ? err.message : String(err)}`, field, ref, err);
+        }
+        if (value === undefined || value === '') {
+            throw new ConnectorResolutionError(`Secret "${ref.key}" (scope "${scope}") required by field "${field}" not found.`, field, ref);
+        }
+        return value;
+    }
+    // Should not reach here — schemas guard inline.
+    throw new ConnectorResolutionError(`Unsupported credential source "${ref.source}" for field "${field}".`, field, ref);
+}
+/**
+ * Resolve an AWS credentials block where each field may be a string or
+ * a CredentialReference.
+ */
+export async function resolveAwsCredentials(creds, opts) {
+    const accessKeyId = typeof creds.accessKeyId === 'string'
+        ? creds.accessKeyId
+        : await resolveCredentialReference('accessKeyId', creds.accessKeyId, opts);
+    const secretAccessKey = typeof creds.secretAccessKey === 'string'
+        ? creds.secretAccessKey
+        : await resolveCredentialReference('secretAccessKey', creds.secretAccessKey, opts);
+    let sessionToken;
+    if (creds.sessionToken !== undefined) {
+        sessionToken =
+            typeof creds.sessionToken === 'string'
+                ? creds.sessionToken
+                : await resolveCredentialReference('sessionToken', creds.sessionToken, opts);
+    }
+    return { accessKeyId, secretAccessKey, sessionToken };
+}
+/**
+ * Resolve an arbitrary config value that may be a bare string or a
+ * CredentialReference.
+ */
+export async function resolveConfigValue(value, field, opts) {
+    if (typeof value === 'string')
+        return value;
+    return resolveCredentialReference(field, value, opts);
+}
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

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

package/dist/schemas.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Connector Base Schemas
+ *
+ * Owned by packages/connector-base.
+ * Descriptor schemas for connector/substrate kind and sub-connector variants.
+ */
+import * as z from 'zod';
+/**
+ * Credential reference for secret store / env lookup.
+ * Mirrored from credential-reference.ts to avoid cross-deps.
+ */
+export declare const CredentialReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    source: z.ZodLiteral<"secret">;
+    key: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    store: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    source: z.ZodLiteral<"env">;
+    key: z.ZodString;
+}, z.core.$strip>], "source">;
+export type CredentialReference = z.infer<typeof CredentialReferenceSchema>;
+/**
+ * AWS-style credentials block (used by S3, SecretsManager, etc).
+ */
+export declare const AwsCredentialsSchema: z.ZodObject<{
+    accessKeyId: z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        source: z.ZodLiteral<"secret">;
+        key: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        store: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        source: z.ZodLiteral<"env">;
+        key: z.ZodString;
+    }, z.core.$strip>], "source">]>;
+    secretAccessKey: z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        source: z.ZodLiteral<"secret">;
+        key: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        store: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        source: z.ZodLiteral<"env">;
+        key: z.ZodString;
+    }, z.core.$strip>], "source">]>;
+    sessionToken: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        source: z.ZodLiteral<"secret">;
+        key: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        store: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        source: z.ZodLiteral<"env">;
+        key: z.ZodString;
+    }, z.core.$strip>], "source">]>>;
+}, z.core.$strip>;
+export type AwsCredentials = z.infer<typeof AwsCredentialsSchema>;
+/**
+ * Base descriptor schema for connector/substrate runtime kind.
+ *
+ * A substrate is a platform-level integration that provides one or more
+ * sub-connectors (e.g., S3, SecretsManager, CloudFront).
+ */
+export declare const ConnectorSubstrateDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"connector/substrate">;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodString;
+    subConnectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        consumer: "consumer";
+        cloud: "cloud";
+        server: "server";
+    }>>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ConnectorSubstrateDescriptor = z.infer<typeof ConnectorSubstrateDescriptorSchema>;
+/**
+ * Descriptor for a sub-connector within a substrate.
+ * Sub-connectors are the actual service clients (e.g., S3, SecretsManager).
+ */
+export declare const SubConnectorDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"connector/sub-connector">;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    substrateId: z.ZodString;
+    service: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SubConnectorDescriptor = z.infer<typeof SubConnectorDescriptorSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;6BAWpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;iBAY7C,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;iBAWvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,67 @@
+/**
+ * Connector Base Schemas
+ *
+ * Owned by packages/connector-base.
+ * Descriptor schemas for connector/substrate kind and sub-connector variants.
+ */
+import * as z from 'zod';
+/**
+ * Credential reference for secret store / env lookup.
+ * Mirrored from credential-reference.ts to avoid cross-deps.
+ */
+export const CredentialReferenceSchema = z.discriminatedUnion('source', [
+    z.object({
+        source: z.literal('secret'),
+        key: z.string(),
+        scope: z.string().optional(),
+        store: z.string().optional(),
+    }),
+    z.object({
+        source: z.literal('env'),
+        key: z.string(),
+    }),
+]);
+/**
+ * AWS-style credentials block (used by S3, SecretsManager, etc).
+ */
+export const AwsCredentialsSchema = z.object({
+    accessKeyId: z.union([z.string(), CredentialReferenceSchema]),
+    secretAccessKey: z.union([z.string(), CredentialReferenceSchema]),
+    sessionToken: z.union([z.string(), CredentialReferenceSchema]).optional(),
+});
+/**
+ * Base descriptor schema for connector/substrate runtime kind.
+ *
+ * A substrate is a platform-level integration that provides one or more
+ * sub-connectors (e.g., S3, SecretsManager, CloudFront).
+ */
+export const ConnectorSubstrateDescriptorSchema = z.object({
+    id: z.string(),
+    kind: z.literal('connector/substrate'),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    provider: z.string(),
+    /** Sub-connectors provided by this substrate */
+    subConnectors: z.array(z.string()).optional(),
+    /** Hardware targets (consumer, cloud) */
+    hardware: z.array(z.enum(['consumer', 'cloud', 'server'])).optional(),
+    /** Whether this substrate is currently enabled */
+    enabled: z.boolean().default(true),
+});
+/**
+ * Descriptor for a sub-connector within a substrate.
+ * Sub-connectors are the actual service clients (e.g., S3, SecretsManager).
+ */
+export const SubConnectorDescriptorSchema = z.object({
+    id: z.string(),
+    kind: z.literal('connector/sub-connector'),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    /** Parent substrate ID */
+    substrateId: z.string(),
+    /** Service type identifier */
+    service: z.string(),
+    /** Whether this sub-connector is currently enabled */
+    enabled: z.boolean().default(true),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;IACvE,CAAC,CAAC,MAAM,CAAC;QACR,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC3B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC5B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACR,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QACxB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;KACf,CAAC;CACF,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,yBAAyB,CAAC,CAAC;IAC7D,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,yBAAyB,CAAC,CAAC;IACjE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,yBAAyB,CAAC,CAAC,CAAC,QAAQ,EAAE;CACzE,CAAC,CAAC;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1D,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,gDAAgD;IAChD,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC7C,yCAAyC;IACzC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrE,kDAAkD;IAClD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAClC,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,0BAA0B;IAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,8BAA8B;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,sDAAsD;IACtD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAClC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vibesdotdev/connector-base",
+  "version": "0.0.1",
+  "description": "Base connector runtime kind and contracts for platform integrations",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/connector.plugin.d.ts",
+      "bun": "./src/connector.plugin.ts",
+      "import": "./dist/connector.plugin.js",
+      "default": "./dist/connector.plugin.js"
+    }
+  },
+  "dependencies": {
+    "@vibesdotdev/runtime": "0.0.1",
+    "zod": "^3.23.8"
+  },
+  "scripts": {
+    "check": "bun --bun tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibesdotdev/monorepo.git",
+    "directory": "packages/connector-base"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "README.md",
+    "SPEC.md",
+    "LICENSE",
+    "!src/**/__tests__/**",
+    "!src/**/__stubs__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!dist/**/__tests__/**",
+    "!dist/**/__stubs__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.js.map",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.d.ts.map"
+  ],
+  "vibes": {
+    "visibility": "public-framework"
+  }
+}

package/src/connector.plugin.ts

@@ -0,0 +1,37 @@
+/**
+ * Connector Base Plugin
+ *
+ * Registers the connector/substrate and connector/sub-connector runtime kinds.
+ * Individual provider packages (connector-aws, connector-azure, …) register
+ * concrete descriptors against these kinds.
+ */
+
+import { createRuntimePlugin, createRuntimeKind } from '@vibesdotdev/runtime';
+import {
+	ConnectorSubstrateDescriptorSchema,
+	SubConnectorDescriptorSchema,
+} from './schemas.ts';
+
+export const connectorBasePlugin = createRuntimePlugin({
+	id: '@vibesdotdev/connector-base',
+	name: 'Connector Base',
+	description: 'Base connector/substrate and connector/sub-connector kinds for platform integrations.',
+
+	onRegister: async (runtime) => {
+		runtime.registerKind(
+			createRuntimeKind({
+				id: 'connector/substrate',
+				descriptorSchema: ConnectorSubstrateDescriptorSchema,
+			})
+		);
+
+		runtime.registerKind(
+			createRuntimeKind({
+				id: 'connector/sub-connector',
+				descriptorSchema: SubConnectorDescriptorSchema,
+			})
+		);
+	},
+});
+
+export default connectorBasePlugin;

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Connector Base
+ *
+ * Base contracts, schemas, and interfaces for platform connector packages.
+ * Owned by packages/connector-base.
+ *
+ * Does NOT contain provider-specific implementations.
+ * Use @vibesdotdev/connector-aws for AWS sub-connectors,
+ * @vibesdotdev/connector-azure for Azure, etc.
+ */
+
+// Descriptor schemas
+export {
+	ConnectorSubstrateDescriptorSchema,
+	SubConnectorDescriptorSchema,
+	CredentialReferenceSchema,
+	AwsCredentialsSchema,
+	type ConnectorSubstrateDescriptor,
+	type SubConnectorDescriptor,
+	type CredentialReference,
+	type AwsCredentials,
+} from './schemas.ts';
+
+// Resolvers (credential resolution, config hydration)
+export {
+	resolveCredentialReference,
+	resolveAwsCredentials,
+	resolveConfigValue,
+	type ResolutionOptions,
+} from './resolver.ts';

package/src/resolver.ts

@@ -0,0 +1,144 @@
+/**
+ * Credential and Config Resolution for Connector Base
+ *
+ * Owned by packages/connector-base.
+ * Provides generic reference-resolution utilities used by all
+ * connector-{provider} packages. Avoids hard dependency on
+ * @vibesdotdev/secrets by accepting an injected store shape.
+ */
+
+import type { CredentialReference, AwsCredentials } from './schemas.ts';
+
+// ---------------------------------------------------------------------------
+// Minimal store interface — avoids pulling in @vibesdotdev/secrets
+// ---------------------------------------------------------------------------
+
+export interface MinimalSecretsStore {
+	get(scope: string, key: string): Promise<string | undefined>;
+}
+
+export interface ResolutionOptions {
+	/** Active environment tier — dev / staging / prod */
+	environment: string;
+	/** Optional secrets store for source: 'secret' refs */
+	secretsStore?: MinimalSecretsStore;
+	/** Optional env reader (defaults to process.env) */
+	envReader?: Record<string, string | undefined>;
+}
+
+export class ConnectorResolutionError extends Error {
+	constructor(
+		message: string,
+		readonly field: string,
+		readonly ref: CredentialReference,
+		readonly cause?: unknown
+	) {
+		super(message);
+		this.name = 'ConnectorResolutionError';
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Value resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a single credential reference to its string value.
+ */
+export async function resolveCredentialReference(
+	field: string,
+	ref: CredentialReference,
+	opts: ResolutionOptions
+): Promise<string> {
+	if (ref.source === 'env') {
+		const reader = opts.envReader ?? (process.env as Record<string, string | undefined>);
+		const value = reader[ref.key];
+		if (value === undefined || value === '') {
+			throw new ConnectorResolutionError(
+				`Environment variable "${ref.key}" required by field "${field}" is not set.`,
+				field,
+				ref
+			);
+		}
+		return value;
+	}
+
+	if (ref.source === 'secret') {
+		if (!opts.secretsStore) {
+			throw new ConnectorResolutionError(
+				`Secrets store unavailable — cannot resolve { source: 'secret', key: '${ref.key}' } for field "${field}".`,
+				field,
+				ref
+			);
+		}
+		const scope = ref.scope ?? opts.environment;
+		let value: string | undefined;
+		try {
+			value = await opts.secretsStore.get(scope, ref.key);
+		} catch (err) {
+			throw new ConnectorResolutionError(
+				`Secrets store lookup failed for "${field}" (key "${ref.key}", scope "${scope}"): ${err instanceof Error ? err.message : String(err)}`,
+				field,
+				ref,
+				err
+			);
+		}
+		if (value === undefined || value === '') {
+			throw new ConnectorResolutionError(
+				`Secret "${ref.key}" (scope "${scope}") required by field "${field}" not found.`,
+				field,
+				ref
+			);
+		}
+		return value;
+	}
+
+	// Should not reach here — schemas guard inline.
+	throw new ConnectorResolutionError(
+		`Unsupported credential source "${(ref as CredentialReference).source}" for field "${field}".`,
+		field,
+		ref
+	);
+}
+
+/**
+ * Resolve an AWS credentials block where each field may be a string or
+ * a CredentialReference.
+ */
+export async function resolveAwsCredentials(
+	creds: AwsCredentials,
+	opts: ResolutionOptions
+): Promise<{ accessKeyId: string; secretAccessKey: string; sessionToken?: string }> {
+	const accessKeyId =
+		typeof creds.accessKeyId === 'string'
+			? creds.accessKeyId
+			: await resolveCredentialReference('accessKeyId', creds.accessKeyId, opts);
+
+	const secretAccessKey =
+		typeof creds.secretAccessKey === 'string'
+			? creds.secretAccessKey
+			: await resolveCredentialReference('secretAccessKey', creds.secretAccessKey, opts);
+
+	let sessionToken: string | undefined;
+	if (creds.sessionToken !== undefined) {
+		sessionToken =
+			typeof creds.sessionToken === 'string'
+				? creds.sessionToken
+				: await resolveCredentialReference('sessionToken', creds.sessionToken, opts);
+	}
+
+	return { accessKeyId, secretAccessKey, sessionToken };
+}
+
+/**
+ * Resolve an arbitrary config value that may be a bare string or a
+ * CredentialReference.
+ */
+export async function resolveConfigValue(
+	value: string | CredentialReference,
+	field: string,
+	opts: ResolutionOptions
+): Promise<string> {
+	if (typeof value === 'string') return value;
+	return resolveCredentialReference(field, value, opts);
+}

package/src/schemas.ts

@@ -0,0 +1,79 @@
+/**
+ * Connector Base Schemas
+ *
+ * Owned by packages/connector-base.
+ * Descriptor schemas for connector/substrate kind and sub-connector variants.
+ */
+
+import * as z from 'zod';
+
+/**
+ * Credential reference for secret store / env lookup.
+ * Mirrored from credential-reference.ts to avoid cross-deps.
+ */
+export const CredentialReferenceSchema = z.discriminatedUnion('source', [
+	z.object({
+		source: z.literal('secret'),
+		key: z.string(),
+		scope: z.string().optional(),
+		store: z.string().optional(),
+	}),
+	z.object({
+		source: z.literal('env'),
+		key: z.string(),
+	}),
+]);
+
+export type CredentialReference = z.infer<typeof CredentialReferenceSchema>;
+
+/**
+ * AWS-style credentials block (used by S3, SecretsManager, etc).
+ */
+export const AwsCredentialsSchema = z.object({
+	accessKeyId: z.union([z.string(), CredentialReferenceSchema]),
+	secretAccessKey: z.union([z.string(), CredentialReferenceSchema]),
+	sessionToken: z.union([z.string(), CredentialReferenceSchema]).optional(),
+});
+
+export type AwsCredentials = z.infer<typeof AwsCredentialsSchema>;
+
+/**
+ * Base descriptor schema for connector/substrate runtime kind.
+ *
+ * A substrate is a platform-level integration that provides one or more
+ * sub-connectors (e.g., S3, SecretsManager, CloudFront).
+ */
+export const ConnectorSubstrateDescriptorSchema = z.object({
+	id: z.string(),
+	kind: z.literal('connector/substrate'),
+	name: z.string().optional(),
+	description: z.string().optional(),
+	provider: z.string(),
+	/** Sub-connectors provided by this substrate */
+	subConnectors: z.array(z.string()).optional(),
+	/** Hardware targets (consumer, cloud) */
+	hardware: z.array(z.enum(['consumer', 'cloud', 'server'])).optional(),
+	/** Whether this substrate is currently enabled */
+	enabled: z.boolean().default(true),
+});
+
+export type ConnectorSubstrateDescriptor = z.infer<typeof ConnectorSubstrateDescriptorSchema>;
+
+/**
+ * Descriptor for a sub-connector within a substrate.
+ * Sub-connectors are the actual service clients (e.g., S3, SecretsManager).
+ */
+export const SubConnectorDescriptorSchema = z.object({
+	id: z.string(),
+	kind: z.literal('connector/sub-connector'),
+	name: z.string().optional(),
+	description: z.string().optional(),
+	/** Parent substrate ID */
+	substrateId: z.string(),
+	/** Service type identifier */
+	service: z.string(),
+	/** Whether this sub-connector is currently enabled */
+	enabled: z.boolean().default(true),
+});
+
+export type SubConnectorDescriptor = z.infer<typeof SubConnectorDescriptorSchema>;