@botiverse/raft-sdk 0.1.0 → 0.1.1

package/README.md

@@ -38,7 +38,49 @@ const { createRaftClient } = require("@botiverse/raft-sdk");
 ```
 
 The credential must belong to the external agent sending the message and must
-include the `send` capability.
+be a long-lived `sk_agent_*` credential with the `send` capability. Other
+credential families fail before transport.
+
+### Persist a credential without the Raft CLI
+
+For a long-running Node.js bot, bootstrap an already-created `sk_agent_*`
+credential once, then build clients from an explicit file store:
+
+```ts
+import {
+  bootstrapRaftCredential,
+  createFileCredentialStore,
+  createRaftClientFromStore,
+} from "@botiverse/raft-sdk";
+
+const store = createFileCredentialStore(
+  "/var/lib/raft-bot-rss-notifier/raft-credential.json",
+);
+
+// First run only. The returned identity never includes the credential bytes.
+await bootstrapRaftCredential({
+  serverUrl: "https://api.raft.build",
+  credential: process.env.RAFT_AGENT_CREDENTIAL!,
+  store,
+});
+
+// Later runs need only the caller-selected store.
+const raft = await createRaftClientFromStore({ store });
+```
+
+The SDK validates the credential through the credential-authenticated Agent API
+and requires its `send` capability before saving it. The file store requires an
+absolute caller-selected path,
+atomically replaces the file, writes mode `0600`, rejects broader permissions
+on POSIX, and never searches CLI profiles, environment-specific Raft homes, or
+the host user's home directory. Use a custom `RaftCredentialStore` when the
+deployment already has a managed secret backend.
+
+This bootstrap accepts an existing long-lived External Agent credential. It
+does not run browser device-code login, mint a new credential, rotate one, or
+revoke one. Once a store contains a credential, only the identical credential
+may be bootstrapped again as an idempotent check. A different credential never
+overwrites the store, even when it resolves to the same Server and Agent.
 
 ## API
 
@@ -58,6 +100,22 @@ Creates a client with these options:
 Invalid client configuration throws `RaftSdkConfigurationError` before a
 request is sent.
 
+### `bootstrapRaftCredential(options)`
+
+Validates an existing External Agent credential, derives its Agent, Server,
+credential, and scope metadata from the Agent API, and saves the complete
+record through `options.store`. It returns only non-secret identity metadata.
+
+### `createFileCredentialStore(path)`
+
+Creates the explicit Node.js file store described above. Relative paths and
+unsafe stored-file permissions fail closed.
+
+### `createRaftClientFromStore(options)`
+
+Loads and validates one `RaftCredentialStore` record, then creates the same
+typed client returned by `createRaftClient`.
+
 ### `client.messages.send(request)`
 
 Sends a message. The request accepts a Raft target, message content, optional

package/dist/cjs/index.cjs

@@ -28,8 +28,12 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    RaftCredentialError: ()=>RaftCredentialError,
     RaftSdkConfigurationError: ()=>RaftSdkConfigurationError,
-    createRaftClient: ()=>createRaftClient
+    bootstrapRaftCredential: ()=>bootstrapRaftCredential,
+    createFileCredentialStore: ()=>createFileCredentialStore,
+    createRaftClient: ()=>createRaftClient,
+    createRaftClientFromStore: ()=>createRaftClientFromStore
 });
 var regexes_namespaceObject = {};
 __webpack_require__.r(regexes_namespaceObject);
@@ -278,7 +282,7 @@ __webpack_require__.d(classic_schemas_namespaceObject, {
     preprocess: ()=>preprocess,
     promise: ()=>promise,
     readonly: ()=>readonly,
-    record: ()=>record,
+    record: ()=>schemas_record,
     refine: ()=>refine,
     set: ()=>schemas_set,
     strictObject: ()=>strictObject,
@@ -5741,7 +5745,7 @@ const ZodRecord = /*@__PURE__*/ $constructor("ZodRecord", (inst, def)=>{
     inst.keyType = def.keyType;
     inst.valueType = def.valueType;
 });
-function record(keyType, valueType, params) {
+function schemas_record(keyType, valueType, params) {
     return new ZodRecord({
         type: "record",
         keyType,
@@ -6180,7 +6184,7 @@ function schemas_json(params) {
             schemas_boolean(),
             schemas_null(),
             schemas_array(jsonSchema),
-            record(schemas_string(), jsonSchema)
+            schemas_record(schemas_string(), jsonSchema)
         ]));
     return jsonSchema;
 }
@@ -6563,6 +6567,7 @@ function requireServerUrl(value) {
 function requireAgentCredential(value) {
     const credential = value.trim();
     if (!credential) throw new RaftSdkConfigurationError("MISSING_AGENT_CREDENTIAL", "Raft Agent credential is required");
+    if (!credential.startsWith("sk_agent_") || 9 === credential.length) throw new RaftSdkConfigurationError("INVALID_AGENT_CREDENTIAL", "Raft Agent credential must be a long-lived External Agent credential");
     return credential;
 }
 function createRaftClient(options) {
@@ -6579,11 +6584,235 @@ function createRaftClient(options) {
         }
     });
 }
+function currentTimeMs() {
+    return Date.now();
+}
+function currentDate() {
+    return new Date(currentTimeMs());
+}
+class RaftCredentialError extends Error {
+    code;
+    name = "RaftCredentialError";
+    constructor(code, message){
+        super(message), this.code = code;
+    }
+}
+function isNonEmptyString(value) {
+    return "string" == typeof value && value.trim().length > 0;
+}
+function parseIdentityResponse(value) {
+    if (!value || "object" != typeof value || Array.isArray(value)) return null;
+    const input = value;
+    if (!isNonEmptyString(input.agentId) || !isNonEmptyString(input.agentName) || null !== input.agentDisplayName && "string" != typeof input.agentDisplayName || !isNonEmptyString(input.serverId) || !isNonEmptyString(input.credentialId) || !Array.isArray(input.scopes) || !input.scopes.every(isNonEmptyString)) return null;
+    return {
+        agentId: input.agentId,
+        agentName: input.agentName,
+        agentDisplayName: input.agentDisplayName,
+        serverId: input.serverId,
+        credentialId: input.credentialId,
+        scopes: [
+            ...input.scopes
+        ]
+    };
+}
+function parseStoredRaftCredential(value) {
+    if (!value || "object" != typeof value || Array.isArray(value)) return null;
+    const input = value;
+    if (1 !== input.schemaVersion || !isNonEmptyString(input.serverUrl) || !isNonEmptyString(input.credential) || !isNonEmptyString(input.storedAt)) return null;
+    const identity = parseIdentityResponse(input);
+    if (!identity || Number.isNaN(Date.parse(input.storedAt))) return null;
+    let serverUrl;
+    let credential;
+    try {
+        serverUrl = requireServerUrl(input.serverUrl);
+        credential = requireAgentCredential(input.credential);
+    } catch  {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        serverUrl,
+        credential,
+        storedAt: input.storedAt,
+        ...identity
+    };
+}
+async function bootstrapRaftCredential(options) {
+    const serverUrl = requireServerUrl(options.serverUrl);
+    const credential = requireAgentCredential(options.credential);
+    const httpFetch = options.fetch ?? globalThis.fetch;
+    let existing;
+    try {
+        existing = await options.store.load();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential could not be checked before saving");
+    }
+    if (existing) {
+        const validatedExisting = parseStoredRaftCredential(existing);
+        if (!validatedExisting) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential record is invalid");
+        existing = validatedExisting;
+        if (existing.serverUrl !== serverUrl || existing.credential !== credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+    }
+    let response;
+    try {
+        response = await httpFetch(`${serverUrl}/internal/agent-api/`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${credential}`
+            }
+        });
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", "Could not reach the Raft Server to verify the Agent credential");
+    }
+    if (!response.ok) {
+        if (401 === response.status || 403 === response.status) throw new RaftCredentialError("CREDENTIAL_REJECTED", "The Raft Server rejected the Agent credential");
+        throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", `The Raft Server could not verify the Agent credential (status ${response.status})`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+    }
+    const identity = parseIdentityResponse(payload);
+    if (!identity) throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+    if (!identity.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The Raft Agent credential does not include the send capability required by this SDK");
+    if (existing && (existing.serverId !== identity.serverId || existing.agentId !== identity.agentId)) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store is already bound to a different Raft Agent identity");
+    if (existing) return {
+        serverUrl,
+        ...identity
+    };
+    const record = {
+        schemaVersion: 1,
+        serverUrl,
+        credential,
+        storedAt: currentDate().toISOString(),
+        ...identity
+    };
+    try {
+        await options.store.save(record);
+    } catch (error) {
+        if (error instanceof RaftCredentialError && "CREDENTIAL_STORE_CONFLICT" === error.code) throw error;
+        throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The verified Agent credential could not be saved");
+    }
+    return {
+        serverUrl,
+        ...identity
+    };
+}
+async function createRaftClientFromStore(options) {
+    let record;
+    try {
+        record = await options.store.load();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential could not be loaded");
+    }
+    if (!record) throw new RaftCredentialError("CREDENTIAL_NOT_FOUND", "No stored Raft Agent credential was found");
+    const validated = parseStoredRaftCredential(record);
+    if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential is invalid");
+    if (!validated.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The stored Raft Agent credential does not include the send capability required by this SDK");
+    return createRaftClient({
+        serverUrl: validated.serverUrl,
+        credential: validated.credential,
+        fetch: options.fetch,
+        headers: options.headers,
+        retry: options.retry,
+        throttle: options.throttle
+    });
+}
+const external_node_crypto_namespaceObject = require("node:crypto");
+const external_node_fs_namespaceObject = require("node:fs");
+const promises_namespaceObject = require("node:fs/promises");
+const external_node_path_namespaceObject = require("node:path");
+const MAX_CREDENTIAL_FILE_BYTES = 65536;
+function createFileCredentialStore(filePath) {
+    if (!filePath.trim() || !(0, external_node_path_namespaceObject.isAbsolute)(filePath)) throw new RaftSdkConfigurationError("INVALID_CREDENTIAL_PATH", "Raft credential file path must be an explicit absolute path");
+    return {
+        load: ()=>loadFileCredential(filePath),
+        async save (record) {
+            const validated = parseStoredRaftCredential(record);
+            if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "Refusing to write an invalid Raft Agent credential record");
+            const directory = (0, external_node_path_namespaceObject.dirname)(filePath);
+            const temporaryPath = `${filePath}.${process.pid}.${(0, external_node_crypto_namespaceObject.randomUUID)()}.tmp`;
+            let handle;
+            try {
+                await (0, promises_namespaceObject.mkdir)(directory, {
+                    recursive: true,
+                    mode: 448
+                });
+                const existing = await loadFileCredential(filePath);
+                if (existing) return void assertSameCredential(existing, validated);
+                handle = await (0, promises_namespaceObject.open)(temporaryPath, "wx", 384);
+                await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+                await handle.sync();
+                await (0, promises_namespaceObject.chmod)(temporaryPath, 384);
+                await handle.close();
+                handle = void 0;
+                try {
+                    await (0, promises_namespaceObject.link)(temporaryPath, filePath);
+                } catch (error) {
+                    if ("EEXIST" !== error.code) throw error;
+                    const winner = await loadFileCredential(filePath);
+                    if (!winner) throw error;
+                    assertSameCredential(winner, validated);
+                }
+                await (0, promises_namespaceObject.unlink)(temporaryPath);
+            } catch (error) {
+                if (handle) await handle.close().catch(()=>void 0);
+                await (0, promises_namespaceObject.unlink)(temporaryPath).catch(()=>void 0);
+                if (error instanceof RaftCredentialError) throw error;
+                throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The Raft Agent credential could not be written atomically");
+            }
+        }
+    };
+}
+async function loadFileCredential(filePath) {
+    let initialMetadata;
+    try {
+        initialMetadata = await (0, promises_namespaceObject.lstat)(filePath);
+    } catch (error) {
+        if ("ENOENT" === error.code) return null;
+        throw fileReadError();
+    }
+    if (!initialMetadata.isFile() || initialMetadata.isSymbolicLink() || initialMetadata.size > MAX_CREDENTIAL_FILE_BYTES) throw fileReadError();
+    let parsed;
+    let handle;
+    try {
+        const noFollow = "win32" === process.platform ? 0 : external_node_fs_namespaceObject.constants.O_NOFOLLOW;
+        handle = await (0, promises_namespaceObject.open)(filePath, external_node_fs_namespaceObject.constants.O_RDONLY | noFollow);
+        const openedMetadata = await handle.stat();
+        if (!openedMetadata.isFile() || openedMetadata.size > MAX_CREDENTIAL_FILE_BYTES || initialMetadata.dev !== openedMetadata.dev || initialMetadata.ino !== openedMetadata.ino) throw fileReadError();
+        if ("win32" !== process.platform && (63 & openedMetadata.mode) !== 0) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file permissions are too broad; expected mode 0600");
+        parsed = JSON.parse(await handle.readFile("utf8"));
+    } catch (error) {
+        if (error instanceof RaftCredentialError) throw error;
+        throw fileReadError();
+    } finally{
+        await handle?.close().catch(()=>void 0);
+    }
+    const record = parseStoredRaftCredential(parsed);
+    if (!record) throw fileReadError();
+    return record;
+}
+function assertSameCredential(existing, candidate) {
+    if (existing.credential !== candidate.credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+}
+function fileReadError() {
+    return new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file is invalid or unreadable");
+}
+exports.RaftCredentialError = __webpack_exports__.RaftCredentialError;
 exports.RaftSdkConfigurationError = __webpack_exports__.RaftSdkConfigurationError;
+exports.bootstrapRaftCredential = __webpack_exports__.bootstrapRaftCredential;
+exports.createFileCredentialStore = __webpack_exports__.createFileCredentialStore;
 exports.createRaftClient = __webpack_exports__.createRaftClient;
+exports.createRaftClientFromStore = __webpack_exports__.createRaftClientFromStore;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "RaftCredentialError",
     "RaftSdkConfigurationError",
-    "createRaftClient"
+    "bootstrapRaftCredential",
+    "createFileCredentialStore",
+    "createRaftClient",
+    "createRaftClientFromStore"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/esm/index.js

@@ -1,3 +1,7 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, link as promises_link, lstat, mkdir, open as promises_open, unlink } from "node:fs/promises";
+import { dirname, isAbsolute } from "node:path";
 var __webpack_require__ = {};
 (()=>{
     __webpack_require__.d = (exports, getters, values)=>{
@@ -209,7 +213,7 @@ __webpack_require__.d(classic_schemas_namespaceObject, {
     preprocess: ()=>preprocess,
     promise: ()=>promise,
     readonly: ()=>readonly,
-    record: ()=>record,
+    record: ()=>schemas_record,
     refine: ()=>refine,
     set: ()=>schemas_set,
     strictObject: ()=>strictObject,
@@ -5734,7 +5738,7 @@ const ZodRecord = /*@__PURE__*/ $constructor("ZodRecord", (inst, def)=>{
     inst.keyType = def.keyType;
     inst.valueType = def.valueType;
 });
-function record(keyType, valueType, params) {
+function schemas_record(keyType, valueType, params) {
     return new ZodRecord({
         type: "record",
         keyType,
@@ -6173,7 +6177,7 @@ function schemas_json(params) {
             schemas_boolean(),
             schemas_null(),
             schemas_array(jsonSchema),
-            record(schemas_string(), jsonSchema)
+            schemas_record(schemas_string(), jsonSchema)
         ]));
     return jsonSchema;
 }
@@ -6556,6 +6560,7 @@ function requireServerUrl(value) {
 function requireAgentCredential(value) {
     const credential = value.trim();
     if (!credential) throw new RaftSdkConfigurationError("MISSING_AGENT_CREDENTIAL", "Raft Agent credential is required");
+    if (!credential.startsWith("sk_agent_") || 9 === credential.length) throw new RaftSdkConfigurationError("INVALID_AGENT_CREDENTIAL", "Raft Agent credential must be a long-lived External Agent credential");
     return credential;
 }
 function createRaftClient(options) {
@@ -6572,4 +6577,216 @@ function createRaftClient(options) {
         }
     });
 }
-export { RaftSdkConfigurationError, createRaftClient };
+function currentTimeMs() {
+    return Date.now();
+}
+function currentDate() {
+    return new Date(currentTimeMs());
+}
+class RaftCredentialError extends Error {
+    code;
+    name = "RaftCredentialError";
+    constructor(code, message){
+        super(message), this.code = code;
+    }
+}
+function isNonEmptyString(value) {
+    return "string" == typeof value && value.trim().length > 0;
+}
+function parseIdentityResponse(value) {
+    if (!value || "object" != typeof value || Array.isArray(value)) return null;
+    const input = value;
+    if (!isNonEmptyString(input.agentId) || !isNonEmptyString(input.agentName) || null !== input.agentDisplayName && "string" != typeof input.agentDisplayName || !isNonEmptyString(input.serverId) || !isNonEmptyString(input.credentialId) || !Array.isArray(input.scopes) || !input.scopes.every(isNonEmptyString)) return null;
+    return {
+        agentId: input.agentId,
+        agentName: input.agentName,
+        agentDisplayName: input.agentDisplayName,
+        serverId: input.serverId,
+        credentialId: input.credentialId,
+        scopes: [
+            ...input.scopes
+        ]
+    };
+}
+function parseStoredRaftCredential(value) {
+    if (!value || "object" != typeof value || Array.isArray(value)) return null;
+    const input = value;
+    if (1 !== input.schemaVersion || !isNonEmptyString(input.serverUrl) || !isNonEmptyString(input.credential) || !isNonEmptyString(input.storedAt)) return null;
+    const identity = parseIdentityResponse(input);
+    if (!identity || Number.isNaN(Date.parse(input.storedAt))) return null;
+    let serverUrl;
+    let credential;
+    try {
+        serverUrl = requireServerUrl(input.serverUrl);
+        credential = requireAgentCredential(input.credential);
+    } catch  {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        serverUrl,
+        credential,
+        storedAt: input.storedAt,
+        ...identity
+    };
+}
+async function bootstrapRaftCredential(options) {
+    const serverUrl = requireServerUrl(options.serverUrl);
+    const credential = requireAgentCredential(options.credential);
+    const httpFetch = options.fetch ?? globalThis.fetch;
+    let existing;
+    try {
+        existing = await options.store.load();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential could not be checked before saving");
+    }
+    if (existing) {
+        const validatedExisting = parseStoredRaftCredential(existing);
+        if (!validatedExisting) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The existing Agent credential record is invalid");
+        existing = validatedExisting;
+        if (existing.serverUrl !== serverUrl || existing.credential !== credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+    }
+    let response;
+    try {
+        response = await httpFetch(`${serverUrl}/internal/agent-api/`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${credential}`
+            }
+        });
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", "Could not reach the Raft Server to verify the Agent credential");
+    }
+    if (!response.ok) {
+        if (401 === response.status || 403 === response.status) throw new RaftCredentialError("CREDENTIAL_REJECTED", "The Raft Server rejected the Agent credential");
+        throw new RaftCredentialError("CREDENTIAL_VERIFY_FAILED", `The Raft Server could not verify the Agent credential (status ${response.status})`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+    }
+    const identity = parseIdentityResponse(payload);
+    if (!identity) throw new RaftCredentialError("CREDENTIAL_RESPONSE_INVALID", "The Raft Server returned an invalid Agent identity response");
+    if (!identity.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The Raft Agent credential does not include the send capability required by this SDK");
+    if (existing && (existing.serverId !== identity.serverId || existing.agentId !== identity.agentId)) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store is already bound to a different Raft Agent identity");
+    if (existing) return {
+        serverUrl,
+        ...identity
+    };
+    const record = {
+        schemaVersion: 1,
+        serverUrl,
+        credential,
+        storedAt: currentDate().toISOString(),
+        ...identity
+    };
+    try {
+        await options.store.save(record);
+    } catch (error) {
+        if (error instanceof RaftCredentialError && "CREDENTIAL_STORE_CONFLICT" === error.code) throw error;
+        throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The verified Agent credential could not be saved");
+    }
+    return {
+        serverUrl,
+        ...identity
+    };
+}
+async function createRaftClientFromStore(options) {
+    let record;
+    try {
+        record = await options.store.load();
+    } catch  {
+        throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential could not be loaded");
+    }
+    if (!record) throw new RaftCredentialError("CREDENTIAL_NOT_FOUND", "No stored Raft Agent credential was found");
+    const validated = parseStoredRaftCredential(record);
+    if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The stored Agent credential is invalid");
+    if (!validated.scopes.includes("send")) throw new RaftCredentialError("CREDENTIAL_SCOPE_MISSING", "The stored Raft Agent credential does not include the send capability required by this SDK");
+    return createRaftClient({
+        serverUrl: validated.serverUrl,
+        credential: validated.credential,
+        fetch: options.fetch,
+        headers: options.headers,
+        retry: options.retry,
+        throttle: options.throttle
+    });
+}
+const MAX_CREDENTIAL_FILE_BYTES = 65536;
+function createFileCredentialStore(filePath) {
+    if (!filePath.trim() || !isAbsolute(filePath)) throw new RaftSdkConfigurationError("INVALID_CREDENTIAL_PATH", "Raft credential file path must be an explicit absolute path");
+    return {
+        load: ()=>loadFileCredential(filePath),
+        async save (record) {
+            const validated = parseStoredRaftCredential(record);
+            if (!validated) throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "Refusing to write an invalid Raft Agent credential record");
+            const directory = dirname(filePath);
+            const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+            let handle;
+            try {
+                await mkdir(directory, {
+                    recursive: true,
+                    mode: 448
+                });
+                const existing = await loadFileCredential(filePath);
+                if (existing) return void assertSameCredential(existing, validated);
+                handle = await promises_open(temporaryPath, "wx", 384);
+                await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+                await handle.sync();
+                await chmod(temporaryPath, 384);
+                await handle.close();
+                handle = void 0;
+                try {
+                    await promises_link(temporaryPath, filePath);
+                } catch (error) {
+                    if ("EEXIST" !== error.code) throw error;
+                    const winner = await loadFileCredential(filePath);
+                    if (!winner) throw error;
+                    assertSameCredential(winner, validated);
+                }
+                await unlink(temporaryPath);
+            } catch (error) {
+                if (handle) await handle.close().catch(()=>void 0);
+                await unlink(temporaryPath).catch(()=>void 0);
+                if (error instanceof RaftCredentialError) throw error;
+                throw new RaftCredentialError("CREDENTIAL_STORE_WRITE_FAILED", "The Raft Agent credential could not be written atomically");
+            }
+        }
+    };
+}
+async function loadFileCredential(filePath) {
+    let initialMetadata;
+    try {
+        initialMetadata = await lstat(filePath);
+    } catch (error) {
+        if ("ENOENT" === error.code) return null;
+        throw fileReadError();
+    }
+    if (!initialMetadata.isFile() || initialMetadata.isSymbolicLink() || initialMetadata.size > MAX_CREDENTIAL_FILE_BYTES) throw fileReadError();
+    let parsed;
+    let handle;
+    try {
+        const noFollow = "win32" === process.platform ? 0 : constants.O_NOFOLLOW;
+        handle = await promises_open(filePath, constants.O_RDONLY | noFollow);
+        const openedMetadata = await handle.stat();
+        if (!openedMetadata.isFile() || openedMetadata.size > MAX_CREDENTIAL_FILE_BYTES || initialMetadata.dev !== openedMetadata.dev || initialMetadata.ino !== openedMetadata.ino) throw fileReadError();
+        if ("win32" !== process.platform && (63 & openedMetadata.mode) !== 0) throw new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file permissions are too broad; expected mode 0600");
+        parsed = JSON.parse(await handle.readFile("utf8"));
+    } catch (error) {
+        if (error instanceof RaftCredentialError) throw error;
+        throw fileReadError();
+    } finally{
+        await handle?.close().catch(()=>void 0);
+    }
+    const record = parseStoredRaftCredential(parsed);
+    if (!record) throw fileReadError();
+    return record;
+}
+function assertSameCredential(existing, candidate) {
+    if (existing.credential !== candidate.credential) throw new RaftCredentialError("CREDENTIAL_STORE_CONFLICT", "The credential store already contains a different Raft Agent credential");
+}
+function fileReadError() {
+    return new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file is invalid or unreadable");
+}
+export { RaftCredentialError, RaftSdkConfigurationError, bootstrapRaftCredential, createFileCredentialStore, createRaftClient, createRaftClientFromStore };

package/dist/index.d.ts

@@ -178,6 +178,32 @@ declare interface AgentApiSendSentResponse {
     [key: string]: unknown;
 }
 
+/**
+ * Validate an existing External Agent credential against Raft, derive its
+ * bound identity from the credential-authenticated `whoami` surface, and save
+ * it through the caller's explicit store. This does not mint or rotate a
+ * credential and never returns the credential bytes.
+ */
+export declare function bootstrapRaftCredential(options: BootstrapRaftCredentialOptions): Promise<RaftCredentialIdentity>;
+
+export declare interface BootstrapRaftCredentialOptions {
+    /** Raft Server origin whose Agent API will validate the credential. */
+    serverUrl: string;
+    /** Existing long-lived External Agent credential (`sk_agent_*`). */
+    credential: string;
+    /** Caller-selected durable store. */
+    store: RaftCredentialStore;
+    /** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
+    fetch?: typeof fetch;
+}
+
+/**
+ * Create a Node.js credential store at one explicit absolute path. The SDK
+ * never discovers CLI profiles or a home directory. Writes use a same-directory
+ * temporary file followed by atomic rename, and the final file is mode 0600.
+ */
+export declare function createFileCredentialStore(filePath: string): RaftCredentialStore;
+
 /**
  * Create a typed client for the credential-derived `/internal/agent-api/*`
  * surface. The SDK does not read CLI profiles, environment variables, or the
@@ -185,6 +211,17 @@ declare interface AgentApiSendSentResponse {
  */
 export declare function createRaftClient(options: CreateRaftClientOptions): RaftClient;
 
+/** Load the caller-selected credential store and create a normal Raft client. */
+export declare function createRaftClientFromStore(options: CreateRaftClientFromStoreOptions): Promise<RaftClient>;
+
+export declare interface CreateRaftClientFromStoreOptions {
+    store: RaftCredentialStore;
+    fetch?: CreateRaftClientOptions["fetch"];
+    headers?: CreateRaftClientOptions["headers"];
+    retry?: CreateRaftClientOptions["retry"];
+    throttle?: CreateRaftClientOptions["throttle"];
+}
+
 export declare interface CreateRaftClientOptions {
     /** Raft Server origin, for example `https://api.raft.build`. */
     serverUrl: string;
@@ -210,12 +247,45 @@ export declare type RaftClientResult = AgentApiMessageClientResult;
 
 export declare type RaftClientSuccess = AgentApiMessageClientSuccess;
 
+export declare class RaftCredentialError extends Error {
+    readonly code: RaftCredentialErrorCode;
+    readonly name = "RaftCredentialError";
+    constructor(code: RaftCredentialErrorCode, message: string);
+}
+
+export declare type RaftCredentialErrorCode = "CREDENTIAL_REJECTED" | "CREDENTIAL_VERIFY_FAILED" | "CREDENTIAL_RESPONSE_INVALID" | "CREDENTIAL_SCOPE_MISSING" | "CREDENTIAL_STORE_READ_FAILED" | "CREDENTIAL_STORE_WRITE_FAILED" | "CREDENTIAL_STORE_CONFLICT" | "CREDENTIAL_NOT_FOUND";
+
+export declare interface RaftCredentialIdentity {
+    serverUrl: string;
+    agentId: string;
+    agentName: string;
+    agentDisplayName: string | null;
+    serverId: string;
+    credentialId: string;
+    scopes: string[];
+}
+
+export declare interface RaftCredentialStore {
+    load(): Promise<StoredRaftCredential | null>;
+    /**
+     * Persist the first credential. Implementations must reject replacement by
+     * a different credential; saving the identical credential may be a no-op.
+     */
+    save(record: StoredRaftCredential): Promise<void>;
+}
+
 export declare class RaftSdkConfigurationError extends Error {
     readonly code: RaftSdkConfigurationErrorCode;
     readonly name = "RaftSdkConfigurationError";
     constructor(code: RaftSdkConfigurationErrorCode, message: string);
 }
 
-export declare type RaftSdkConfigurationErrorCode = "MISSING_SERVER_URL" | "INVALID_SERVER_URL" | "MISSING_AGENT_CREDENTIAL";
+export declare type RaftSdkConfigurationErrorCode = "MISSING_SERVER_URL" | "INVALID_SERVER_URL" | "MISSING_AGENT_CREDENTIAL" | "INVALID_AGENT_CREDENTIAL" | "INVALID_CREDENTIAL_PATH";
+
+export declare interface StoredRaftCredential extends RaftCredentialIdentity {
+    schemaVersion: 1;
+    credential: string;
+    storedAt: string;
+}
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Typed Raft Agent API client for external agents and bots.",
   "type": "module",
   "main": "./dist/cjs/index.cjs",