@datacules/agent-identity-store-spiffe 0.11.0 → 0.11.1

package/LICENSE

@@ -0,0 +1,109 @@
+Datacules Agent Identity License — Version 1.0
+Copyright (c) 2026 Datacules LLC. All rights reserved.
+
+─────────────────────────────────────────────────────────────────────────────
+PREAMBLE
+─────────────────────────────────────────────────────────────────────────────
+
+This software — Agent Identity & Auth Patterns — is developed and owned by
+Datacules LLC. It is made available to the public as open-source software
+under the permissive terms below.
+
+Datacules LLC retains ownership and authorship of this software while
+granting broad, royalty-free rights for anyone to use, copy, modify, and
+distribute it — in commercial or non-commercial contexts — without requiring
+that derivative works also become open source.
+
+─────────────────────────────────────────────────────────────────────────────
+TERMS AND CONDITIONS
+─────────────────────────────────────────────────────────────────────────────
+
+1. PERMISSION TO USE
+
+   Permission is hereby granted, free of charge, to any person or
+   organization obtaining a copy of this software and associated
+   documentation files (the "Software"), to use, copy, modify, merge,
+   publish, distribute, sublicense, and/or sell copies of the Software,
+   and to permit persons to whom the Software is furnished to do so,
+   subject to the conditions below.
+
+2. ATTRIBUTION
+
+   a. Redistributions of source code must retain this copyright notice,
+      this list of conditions, and the disclaimer below.
+
+   b. Redistributions in binary form or as a product must reproduce this
+      copyright notice, this list of conditions, and the disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+   c. Neither the name "Datacules LLC" nor the names of its contributors
+      may be used to endorse or promote products derived from this Software
+      without prior written permission from Datacules LLC.
+
+3. COMMERCIAL USE
+
+   Use of this Software in commercial products, SaaS platforms, internal
+   enterprise tools, or any revenue-generating context is explicitly
+   permitted without royalty, fee, or additional licensing agreement,
+   provided that the conditions in Section 2 (Attribution) are met.
+
+4. NO COPYLEFT / NO VIRAL REQUIREMENT
+
+   This license does NOT require that derivative works, modifications,
+   or software that uses or embeds this Software be made open source.
+   You may incorporate this Software into proprietary or closed-source
+   products under your own license terms.
+
+5. MODIFICATIONS
+
+   Modified versions of the Software may be distributed under the same
+   terms as this license or under any other permissive open-source
+   license (e.g. MIT, Apache 2.0, BSD), provided that:
+
+   a. The original copyright notice of Datacules LLC is preserved.
+   b. Modifications are clearly documented and distinguished from the
+      original work.
+
+6. COMPATIBILITY
+
+   This license is compatible with other permissive open-source licenses
+   such as MIT, BSD 2-Clause, BSD 3-Clause, and Apache License 2.0. It
+   is also GPL-compatible — this Software may coexist with GPL-licensed
+   code, though this Software itself is not distributed under the GPL.
+
+─────────────────────────────────────────────────────────────────────────────
+DISCLAIMER
+─────────────────────────────────────────────────────────────────────────────
+
+THIS SOFTWARE IS PROVIDED BY DATACULES LLC AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+AND NON-INFRINGEMENT ARE DISCLAIMED.
+
+IN NO EVENT SHALL DATACULES LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+─────────────────────────────────────────────────────────────────────────────
+SUMMARY (non-binding)
+─────────────────────────────────────────────────────────────────────────────
+
+  ✔  Use freely — commercial, proprietary, or open-source projects
+  ✔  Modify and distribute with or without changes
+  ✔  Sell products built on this Software
+  ✔  No royalties or fees
+  ✔  No requirement to open-source your own code
+  ✔  Attribution to Datacules LLC required in source and binary distributions
+  ✗  Do not use "Datacules LLC" to endorse derived products without permission
+
+─────────────────────────────────────────────────────────────────────────────
+CONTACT
+─────────────────────────────────────────────────────────────────────────────
+
+Datacules LLC
+For licensing enquiries: legal@datacules.com
+Product: https://github.com/hvrcharon1/agent-identity

package/dist/cjs/SpiffeCredentialStore.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * @datacules/agent-identity-store-spiffe
+ *
+ * SPIFFE/SPIRE workload identity credential store.
+ *
+ * Instead of static credentials stored in a vault, this store uses the
+ * SPIFFE Workload API to fetch short-lived X.509 SVIDs (SPIFFE Verifiable
+ * Identity Documents) on demand. Each SVID is valid for a configurable TTL
+ * (default: 1 hour) and is automatically rotated by the SPIRE agent.
+ *
+ * How it works:
+ *   1. On resolve(), the store looks up a Credential by ref.
+ *   2. If the credential is of kind 'spiffe', it calls the Workload API
+ *      to fetch the current X.509 SVID bundle for the workload's SPIFFE ID.
+ *   3. The SVID's leaf certificate + private key are returned as the
+ *      credential ref — downstream services verify the chain against the
+ *      trust bundle, not against a static API key.
+ *   4. The store caches unexpired SVIDs in memory to avoid Workload API
+ *      round-trips on every resolve() call.
+ *
+ * Zero static secrets at rest — a full store compromise yields only
+ * workload metadata, not any usable credential material.
+ *
+ * Compatible with: SPIRE server, SPIRE agent, any SPIFFE-compliant runtime.
+ * Workload API socket: unix:///tmp/spire-agent/public/api.sock (default)
+ *                   or SPIFFE_ENDPOINT_SOCKET env var.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpiffeCredentialStore = void 0;
+// ─── SpiffeCredentialStore ────────────────────────────────────────────────────
+class SpiffeCredentialStore {
+    constructor(options) {
+        this.svidCache = new Map();
+        this.client = null;
+        // Migration reservation map: ref → { migrationId, expiresAt }
+        this.reservations = new Map();
+        this.options = {
+            endpointSocket: options.endpointSocket ??
+                (typeof process !== 'undefined'
+                    ? process.env['SPIFFE_ENDPOINT_SOCKET'] ?? 'unix:///tmp/spire-agent/public/api.sock'
+                    : 'unix:///tmp/spire-agent/public/api.sock'),
+            cacheTtlSeconds: options.cacheTtlSeconds ?? 3300,
+            trustDomain: options.trustDomain ?? 'example.org',
+            credentials: options.credentials,
+        };
+    }
+    // ── CredentialStore interface ──────────────────────────────────────────────
+    async findByRef(ref) {
+        const meta = this.options.credentials.find((c) => c.ref === ref && c.status === 'active');
+        if (!meta)
+            return null;
+        // Fetch the SVID for this ref (cache hit if not expired)
+        const svid = await this.getSvid(ref);
+        if (!svid)
+            return null;
+        // Return the credential with the SVID PEM as the live ref value.
+        // Callers use the ref to authenticate — here it contains the PEM cert chain.
+        return {
+            ...meta,
+            ref: svid.ref,
+            expiresAt: svid.expiresAt.toISOString(),
+        };
+    }
+    async listActive() {
+        return this.options.credentials.filter((c) => c.status === 'active');
+    }
+    async listByKind(kind) {
+        return this.options.credentials.filter((c) => c.kind === kind && c.status === 'active');
+    }
+    async reserve(ref, migrationId, ttlSeconds) {
+        const existing = this.reservations.get(ref);
+        const now = Date.now();
+        if (existing && existing.expiresAt > now && existing.migrationId !== migrationId) {
+            return false; // held by another migration
+        }
+        this.reservations.set(ref, { migrationId, expiresAt: now + ttlSeconds * 1000 });
+        return true;
+    }
+    async release(ref, migrationId) {
+        const existing = this.reservations.get(ref);
+        if (existing?.migrationId === migrationId) {
+            this.reservations.delete(ref);
+        }
+    }
+    // ── Workload API interaction ───────────────────────────────────────────────
+    async getSvid(ref) {
+        const cached = this.svidCache.get(ref);
+        if (cached && cached.expiresAt > new Date())
+            return cached;
+        try {
+            const client = await this.getClient();
+            const response = await client.fetchX509Svids();
+            // Match SVID by hint (ref) or by spiffeId path segment
+            const matched = response.svids.find((s) => s.hint === ref ||
+                s.spiffeId.toString().endsWith(`/${ref}`) ||
+                s.spiffeId.toString() === `spiffe://${this.options.trustDomain}/${ref}`);
+            if (!matched)
+                return null;
+            const entry = {
+                ref: matched.x509Svid.toString(), // PEM cert chain
+                expiresAt: new Date(Date.now() + this.options.cacheTtlSeconds * 1000),
+                spiffeId: matched.spiffeId.toString(),
+            };
+            this.svidCache.set(ref, entry);
+            return entry;
+        }
+        catch (err) {
+            // Workload API unavailable — fail open with null so the router
+            // returns 'no credential matched' rather than crashing
+            console.error('[SpiffeCredentialStore] Workload API error:', err);
+            return null;
+        }
+    }
+    async getClient() {
+        if (this.client)
+            return this.client;
+        // Lazy-load the optional peer dep
+        try {
+            const mod = await Promise.resolve(`${'@spiffe/spiffe-workload-api'}`).then(s => __importStar(require(s)));
+            const WorkloadApiClientClass = mod
+                .WorkloadApiClient;
+            if (!WorkloadApiClientClass)
+                throw new Error('WorkloadApiClient not found in module');
+            this.client = new WorkloadApiClientClass(this.options.endpointSocket);
+            return this.client;
+        }
+        catch {
+            throw new Error('[SpiffeCredentialStore] @spiffe/spiffe-workload-api is required but not installed. ' +
+                'Run: npm install @spiffe/spiffe-workload-api');
+        }
+    }
+    /** Flush the SVID cache — useful in tests or after a known rotation event. */
+    flushCache() {
+        this.svidCache.clear();
+    }
+    /** Close the Workload API connection. */
+    close() {
+        this.client?.close();
+        this.client = null;
+    }
+}
+exports.SpiffeCredentialStore = SpiffeCredentialStore;
+//# sourceMappingURL=SpiffeCredentialStore.js.map

package/dist/cjs/SpiffeCredentialStore.js.map

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

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpiffeCredentialStore = void 0;
+var SpiffeCredentialStore_1 = require("./SpiffeCredentialStore");
+Object.defineProperty(exports, "SpiffeCredentialStore", { enumerable: true, get: function () { return SpiffeCredentialStore_1.SpiffeCredentialStore; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA"}

package/dist/esm/SpiffeCredentialStore.js

@@ -0,0 +1,140 @@
+/**
+ * @datacules/agent-identity-store-spiffe
+ *
+ * SPIFFE/SPIRE workload identity credential store.
+ *
+ * Instead of static credentials stored in a vault, this store uses the
+ * SPIFFE Workload API to fetch short-lived X.509 SVIDs (SPIFFE Verifiable
+ * Identity Documents) on demand. Each SVID is valid for a configurable TTL
+ * (default: 1 hour) and is automatically rotated by the SPIRE agent.
+ *
+ * How it works:
+ *   1. On resolve(), the store looks up a Credential by ref.
+ *   2. If the credential is of kind 'spiffe', it calls the Workload API
+ *      to fetch the current X.509 SVID bundle for the workload's SPIFFE ID.
+ *   3. The SVID's leaf certificate + private key are returned as the
+ *      credential ref — downstream services verify the chain against the
+ *      trust bundle, not against a static API key.
+ *   4. The store caches unexpired SVIDs in memory to avoid Workload API
+ *      round-trips on every resolve() call.
+ *
+ * Zero static secrets at rest — a full store compromise yields only
+ * workload metadata, not any usable credential material.
+ *
+ * Compatible with: SPIRE server, SPIRE agent, any SPIFFE-compliant runtime.
+ * Workload API socket: unix:///tmp/spire-agent/public/api.sock (default)
+ *                   or SPIFFE_ENDPOINT_SOCKET env var.
+ */
+// ─── SpiffeCredentialStore ────────────────────────────────────────────────────
+export class SpiffeCredentialStore {
+    constructor(options) {
+        this.svidCache = new Map();
+        this.client = null;
+        // Migration reservation map: ref → { migrationId, expiresAt }
+        this.reservations = new Map();
+        this.options = {
+            endpointSocket: options.endpointSocket ??
+                (typeof process !== 'undefined'
+                    ? process.env['SPIFFE_ENDPOINT_SOCKET'] ?? 'unix:///tmp/spire-agent/public/api.sock'
+                    : 'unix:///tmp/spire-agent/public/api.sock'),
+            cacheTtlSeconds: options.cacheTtlSeconds ?? 3300,
+            trustDomain: options.trustDomain ?? 'example.org',
+            credentials: options.credentials,
+        };
+    }
+    // ── CredentialStore interface ──────────────────────────────────────────────
+    async findByRef(ref) {
+        const meta = this.options.credentials.find((c) => c.ref === ref && c.status === 'active');
+        if (!meta)
+            return null;
+        // Fetch the SVID for this ref (cache hit if not expired)
+        const svid = await this.getSvid(ref);
+        if (!svid)
+            return null;
+        // Return the credential with the SVID PEM as the live ref value.
+        // Callers use the ref to authenticate — here it contains the PEM cert chain.
+        return {
+            ...meta,
+            ref: svid.ref,
+            expiresAt: svid.expiresAt.toISOString(),
+        };
+    }
+    async listActive() {
+        return this.options.credentials.filter((c) => c.status === 'active');
+    }
+    async listByKind(kind) {
+        return this.options.credentials.filter((c) => c.kind === kind && c.status === 'active');
+    }
+    async reserve(ref, migrationId, ttlSeconds) {
+        const existing = this.reservations.get(ref);
+        const now = Date.now();
+        if (existing && existing.expiresAt > now && existing.migrationId !== migrationId) {
+            return false; // held by another migration
+        }
+        this.reservations.set(ref, { migrationId, expiresAt: now + ttlSeconds * 1000 });
+        return true;
+    }
+    async release(ref, migrationId) {
+        const existing = this.reservations.get(ref);
+        if (existing?.migrationId === migrationId) {
+            this.reservations.delete(ref);
+        }
+    }
+    // ── Workload API interaction ───────────────────────────────────────────────
+    async getSvid(ref) {
+        const cached = this.svidCache.get(ref);
+        if (cached && cached.expiresAt > new Date())
+            return cached;
+        try {
+            const client = await this.getClient();
+            const response = await client.fetchX509Svids();
+            // Match SVID by hint (ref) or by spiffeId path segment
+            const matched = response.svids.find((s) => s.hint === ref ||
+                s.spiffeId.toString().endsWith(`/${ref}`) ||
+                s.spiffeId.toString() === `spiffe://${this.options.trustDomain}/${ref}`);
+            if (!matched)
+                return null;
+            const entry = {
+                ref: matched.x509Svid.toString(), // PEM cert chain
+                expiresAt: new Date(Date.now() + this.options.cacheTtlSeconds * 1000),
+                spiffeId: matched.spiffeId.toString(),
+            };
+            this.svidCache.set(ref, entry);
+            return entry;
+        }
+        catch (err) {
+            // Workload API unavailable — fail open with null so the router
+            // returns 'no credential matched' rather than crashing
+            console.error('[SpiffeCredentialStore] Workload API error:', err);
+            return null;
+        }
+    }
+    async getClient() {
+        if (this.client)
+            return this.client;
+        // Lazy-load the optional peer dep
+        try {
+            const mod = await import('@spiffe/spiffe-workload-api');
+            const WorkloadApiClientClass = mod
+                .WorkloadApiClient;
+            if (!WorkloadApiClientClass)
+                throw new Error('WorkloadApiClient not found in module');
+            this.client = new WorkloadApiClientClass(this.options.endpointSocket);
+            return this.client;
+        }
+        catch {
+            throw new Error('[SpiffeCredentialStore] @spiffe/spiffe-workload-api is required but not installed. ' +
+                'Run: npm install @spiffe/spiffe-workload-api');
+        }
+    }
+    /** Flush the SVID cache — useful in tests or after a known rotation event. */
+    flushCache() {
+        this.svidCache.clear();
+    }
+    /** Close the Workload API connection. */
+    close() {
+        this.client?.close();
+        this.client = null;
+    }
+}
+//# sourceMappingURL=SpiffeCredentialStore.js.map

package/dist/esm/SpiffeCredentialStore.js.map

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

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { SpiffeCredentialStore } from './SpiffeCredentialStore';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/types/SpiffeCredentialStore.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @datacules/agent-identity-store-spiffe
+ *
+ * SPIFFE/SPIRE workload identity credential store.
+ *
+ * Instead of static credentials stored in a vault, this store uses the
+ * SPIFFE Workload API to fetch short-lived X.509 SVIDs (SPIFFE Verifiable
+ * Identity Documents) on demand. Each SVID is valid for a configurable TTL
+ * (default: 1 hour) and is automatically rotated by the SPIRE agent.
+ *
+ * How it works:
+ *   1. On resolve(), the store looks up a Credential by ref.
+ *   2. If the credential is of kind 'spiffe', it calls the Workload API
+ *      to fetch the current X.509 SVID bundle for the workload's SPIFFE ID.
+ *   3. The SVID's leaf certificate + private key are returned as the
+ *      credential ref — downstream services verify the chain against the
+ *      trust bundle, not against a static API key.
+ *   4. The store caches unexpired SVIDs in memory to avoid Workload API
+ *      round-trips on every resolve() call.
+ *
+ * Zero static secrets at rest — a full store compromise yields only
+ * workload metadata, not any usable credential material.
+ *
+ * Compatible with: SPIRE server, SPIRE agent, any SPIFFE-compliant runtime.
+ * Workload API socket: unix:///tmp/spire-agent/public/api.sock (default)
+ *                   or SPIFFE_ENDPOINT_SOCKET env var.
+ */
+import type { Credential, CredentialStore } from '@datacules/agent-identity';
+export interface SpiffeCredentialStoreOptions {
+    /**
+     * SPIFFE Workload API endpoint.
+     * Defaults to SPIFFE_ENDPOINT_SOCKET env var or
+     * unix:///tmp/spire-agent/public/api.sock
+     */
+    endpointSocket?: string;
+    /**
+     * Cache SVIDs for up to this many seconds before re-fetching.
+     * Should be less than the SVID TTL configured in SPIRE.
+     * Default: 3300 (55 minutes — 5 minute buffer before 1h SVID expires).
+     */
+    cacheTtlSeconds?: number;
+    /**
+     * Trust domain for SPIFFE IDs (e.g. 'example.org').
+     * Used to construct SPIFFE IDs when matching hints.
+     */
+    trustDomain?: string;
+    /**
+     * Static credential metadata (id, name, kind, scope, etc.) indexed by ref.
+     * The ref is matched against SVID hints to find the right SVID.
+     * Credential values (actual secrets) come from the Workload API, not here.
+     */
+    credentials: Credential[];
+}
+export declare class SpiffeCredentialStore implements CredentialStore {
+    private readonly options;
+    private svidCache;
+    private client;
+    private reservations;
+    constructor(options: SpiffeCredentialStoreOptions);
+    findByRef(ref: string): Promise<Credential | null>;
+    listActive(): Promise<Credential[]>;
+    listByKind(kind: 'fixed' | 'user-delegated'): Promise<Credential[]>;
+    reserve(ref: string, migrationId: string, ttlSeconds: number): Promise<boolean>;
+    release(ref: string, migrationId: string): Promise<void>;
+    private getSvid;
+    private getClient;
+    /** Flush the SVID cache — useful in tests or after a known rotation event. */
+    flushCache(): void;
+    /** Close the Workload API connection. */
+    close(): void;
+}
+//# sourceMappingURL=SpiffeCredentialStore.d.ts.map

package/dist/types/SpiffeCredentialStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpiffeCredentialStore.d.ts","sourceRoot":"","sources":["../../src/SpiffeCredentialStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAsB,MAAM,2BAA2B,CAAC;AAqCjG,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAID,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,MAAM,CAAkC;IAEhD,OAAO,CAAC,YAAY,CAAiE;gBAEzE,OAAO,EAAE,4BAA4B;IAe3C,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiBlD,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAInC,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAMnE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU/E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAShD,OAAO;YAkCP,SAAS;IAoBvB,8EAA8E;IAC9E,UAAU,IAAI,IAAI;IAIlB,yCAAyC;IACzC,KAAK,IAAI,IAAI;CAId"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { SpiffeCredentialStore } from './SpiffeCredentialStore';
+export type { SpiffeCredentialStoreOptions } from './SpiffeCredentialStore';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@datacules/agent-identity-store-spiffe",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "SPIFFE/SPIRE workload identity credential store for @datacules/agent-identity",
   "private": false,
+  "author": "Datacules LLC",
+  "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "exports": {
     ".": {
@@ -16,14 +18,15 @@
   "types": "./dist/types/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json",
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@datacules/agent-identity": "^0.6.0",
+    "@datacules/agent-identity": "^0.11.1",
     "@spiffe/spiffe-workload-api": "^1.0.0"
   },
   "peerDependenciesMeta": {
@@ -35,9 +38,19 @@
     "@datacules/agent-identity": "*",
     "typescript": "^5"
   },
-  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/hvrcharon1/agent-identity"
-  }
+    "url": "https://github.com/hvrcharon1/agent-identity.git",
+    "directory": "packages/stores/spiffe"
+  },
+  "keywords": [
+    "agent-identity",
+    "spiffe",
+    "spire",
+    "workload-identity",
+    "x509",
+    "zero-trust",
+    "ai-agents",
+    "datacules"
+  ]
 }